HTML-FIRST API CENTERGOVERNED REFERENCE

Trusted ThingID API Center

Human-readable API documentation for resolver, DPP, claims, evidence, mandates, lifecycle, search, connectors and device attestation.

Read Integration Guide View API Reference

API OPERATIONS

Business semantics travel with the protocol.

Every operation exposes purpose, scope, state, evidence, errors and recovery.

GET/v1/resolve/{identifier}REFERENCE CONTRACT

Resolve an official identifier or governed alias

Resolve an official identifier or governed alias while returning authority and assurance context.

Actor: Consumer app · operator portal · external integrator
OAuth scope: thing.read
State before: Identifier is presented; no platform authority is inferred.
State after: A resolution result and source-authority context are returned; no legal relationship changes.

Evidence: Resolution/correlation audit context; no material business state change.
Event: None required for read operation
Errors: 404 unknown identifier · 401/403 authentication/authorization · 409 ambiguous/collision context where implementation requires review
Retry / recovery: Safe read retry with correlation ID.

Request / response examples

REQUEST / INPUT

{"identifier":"0950600012345"}

RESPONSE / OUTCOME

{"officialIdentifier":"0950600012345","resolvedThingId":"ttid:thing:01HV...","aliases":["urn:epc:id:sgtin:..."],"authority":{"domain":"official-identifier","source":"issuing-scheme"},"assurance":{"level":"source-aware"}}

GET/v1/dpp/{identifier}REFERENCE CONTRACT

Read a policy-qualified DPP view

Read a policy-qualified DPP view for the resolved product context.

Actor: DPP Viewer · Consumer · authorised stakeholder
OAuth scope: dpp.read
State before: Identity, purpose, mandate and disclosure context are evaluated.
State after: A composed public/restricted view is returned; source records remain authoritative.

Evidence: Policy/disclosure decision may be audited according to deployment policy.
Event: None required for read operation
Errors: 404 no view · 401/403 denied · 424 authoritative source unavailable where applicable
Retry / recovery: Safe read retry; degraded-mode behavior must be explicit.

Request / response examples

REQUEST / INPUT

{"identifier":"0950600012345","purpose":"consumer-view"}

RESPONSE / OUTCOME

{"identifier":"0950600012345","view":"public","profileVersion":"example-2026.1","fields":{"model":"Example Product"},"authority":{"registryStatus":"external-source"}}

POST/v1/claimsREFERENCE CONTRACT

Submit an evidence-backed claim

Submit an evidence-backed claim for governed evaluation and lifecycle management.

Actor: Authorised issuer · economic operator · service workflow
OAuth scope: claim.write
State before: Evidence and issuer context exist; claim is not yet accepted.
State after: Claim enters governed processing; acceptance is not equivalent to legal authority.

Evidence: Evidence references, issuer context, policy version and audit record.
Event: claim.status.changed
Errors: 400 schema · 401/403 scope/mandate · 409 duplicate/idempotency · 422 policy/evidence failure
Retry / recovery: Use Idempotency-Key for write retry.

Request / response examples

REQUEST / INPUT

{"subject":"ttid:thing:01HV...","claimType":"ownership","issuer":"org:example","evidenceRefs":["evidence:transfer:123"]}

RESPONSE / OUTCOME

{"claimId":"claim:01...","status":"pending-governed-evaluation","correlationId":"corr-..."}

GET/v1/claims/{claimId}REFERENCE CONTRACT

Get a claim and provenance/status context

Read a claim together with provenance and status context.

Actor: Portal · verifier · administrator
OAuth scope: claim.read
State before: Claim identifier is known.
State after: Current governed claim/status context is returned.

Evidence: Read audit according to policy; provenance links preserved.
Event: claim.status.changed (related)
Errors: 404 claim not found · 403 disclosure denied
Retry / recovery: Safe read retry.

Request / response examples

REQUEST / INPUT

{"subject":"ttid:thing:01HV...","claimType":"ownership","issuer":"org:example","evidenceRefs":["evidence:transfer:123"]}

RESPONSE / OUTCOME

{"claimId":"claim:01...","status":"pending-governed-evaluation","correlationId":"corr-..."}

POST/v1/evidenceREFERENCE CONTRACT

Register an evidence reference

Register an evidence reference and provenance metadata without moving private keys or authoritative source data into the DPP repository.

Actor: Business service · connector · portal workflow
OAuth scope: evidence.write
State before: Source evidence exists and has a defined retention/integrity context.
State after: Evidence reference enters governed evidence processing.

Evidence: Source, type, digest, timestamp and provenance metadata.
Event: evidence.recorded
Errors: 400 schema · 409 idempotency · 422 integrity/provenance policy failure
Retry / recovery: Use Idempotency-Key.

Request / response examples

REQUEST / INPUT

{"source":"repair-order:7781","type":"repair-record","digest":"sha256:...","timestamp":"2026-09-02T00:00:00Z"}

RESPONSE / OUTCOME

{"evidenceId":"evidence:01...","status":"accepted-for-processing"}

POST/v1/mandatesREFERENCE CONTRACT

Issue or submit a mandate/delegation record

Issue or submit a mandate/delegation record with explicit scope and expiry.

Actor: Owner · organisation · administrator
OAuth scope: mandate.write
State before: Issuer is authenticated and authorized to delegate the requested scope.
State after: Mandate enters governed lifecycle; it does not merge ownership and delegation semantics.

Evidence: Issuer, subject, scope, validity and supporting evidence.
Event: claim.status.changed or mandate lifecycle event in deployment profile
Errors: 403 issuer lacks authority · 409 duplicate · 422 scope/expiry invalid
Retry / recovery: Use Idempotency-Key.

Request / response examples

REQUEST / INPUT

{"issuer":"owner:123","subject":"repairer:456","scope":["repair.write"],"validUntil":"2026-12-31T23:59:59Z"}

RESPONSE / OUTCOME

{"mandateId":"mandate:01...","status":"active-after-policy-evaluation"}

POST/v1/things/{thingId}/transitionsREFERENCE CONTRACT

Request a material lifecycle transition

Request a material lifecycle transition such as repair, transfer, restriction or close-out under policy and evidence controls.

Actor: Economic Operator · field operations · regulator workflow
OAuth scope: lifecycle.write
State before: Current state, actor mandate and preconditions are known.
State after: Transition is accepted for evaluation; resulting state is only committed after policy/evidence conditions succeed.

Evidence: Preconditions, evidenceRefs, trustedTimeRef and policyVersion.
Event: thing.lifecycle.changed
Errors: 409 invalid current state · 422 precondition/evidence failure · 403 mandate denied
Retry / recovery: Use Idempotency-Key and reconcile ambiguous outcomes.

Request / response examples

REQUEST / INPUT

{"event":"repair.completed","actor":"repairer:456","preconditions":["mandate-valid"],"evidenceRefs":["evidence:repair:01"],"policyVersion":"repair-policy-2026.1"}

RESPONSE / OUTCOME

{"transitionId":"transition:01...","status":"accepted-for-evaluation"}

GET/v1/searchREFERENCE CONTRACT

Search a derived read model

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

Actor: Portal · operations · authorised user
OAuth scope: thing.read
State before: Search query and disclosure context are supplied.
State after: Derived results are returned and can be resolved back to authoritative/source-aware records.

Evidence: Search access may be audited by deployment policy.
Event: None
Errors: 400 invalid query · 403 disclosure denied · 503 index unavailable
Retry / recovery: Safe read retry.

Request / response examples

REQUEST / INPUT

{"q":"battery model X"}

RESPONSE / OUTCOME

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

GET/v1/connectors/{connectorId}/healthREFERENCE CONTRACT

Get connector operational state

Read operational connector state without conflating transport health with authoritative business status.

Actor: Operations Administrator · integration engineer
OAuth scope: connector.read
State before: Connector exists.
State after: Operational health is returned.

Evidence: Operational telemetry and connector-status evidence.
Event: connector.status.changed
Errors: 404 connector · 403 operations scope
Retry / recovery: Safe read retry.

Request / response examples

REQUEST / INPUT

{"connectorId":"eu-dpp-registry"}

RESPONSE / OUTCOME

{"connectorId":"eu-dpp-registry","transport":"healthy","businessReconciliation":"required","authority":"external"}

POST/v1/connectors/{connectorId}/reconcileREFERENCE CONTRACT

Request business/system reconciliation

Request business/system reconciliation after retry, outage or ambiguous external outcome.

Actor: Operations Administrator · automated recovery workflow
OAuth scope: connector.operate
State before: A discrepancy or ambiguous external outcome has been identified.
State after: Reconciliation workflow is queued; external authority remains external.

Evidence: Trigger reason, source/target state, retry history and reconciliation result.
Event: connector.status.changed and domain-specific result event
Errors: 409 reconciliation already active · 422 unsupported discrepancy · 503 external system unavailable
Retry / recovery: Idempotent request; reconciliation is distinct from transport retry.

Request / response examples

REQUEST / INPUT

{"connectorId":"eu-dpp-registry"}

RESPONSE / OUTCOME

{"connectorId":"eu-dpp-registry","transport":"healthy","businessReconciliation":"required","authority":"external"}

POST/v1/devices/{deviceId}/attestREFERENCE CONTRACT

Submit device attestation evidence for appraisal

Submit device attestation evidence for appraisal under a versioned runtime policy.

Actor: Thing Agent · Device Operations
OAuth scope: device.attest
State before: Device identity/certificate state and challenge context are known.
State after: Evidence is accepted for appraisal; certificate validity alone does not become runtime trust.

Evidence: Attestation evidence, appraisal policy/version, freshness/challenge context.
Event: Deployment-specific device appraisal event
Errors: 401/403 device identity/scope · 409 replay/freshness · 422 evidence/appraisal failure
Retry / recovery: Retry only with valid freshness/challenge semantics.

Request / response examples

REQUEST / INPUT

{"deviceId":"device:123","attestation":{"format":"deployment-selected","challenge":"..."}}

RESPONSE / OUTCOME

{"appraisalId":"appraisal:01...","status":"accepted-for-appraisal","certificateStatus":"separate-context"}

LOCAL STATIC EXPLORER

Explore the reference contract without a server.

REQUEST

REFERENCE RESPONSE

Local static explorer: examples only. It does not call a production API.

SPECIFICATIONS

Machine-readable is a secondary action.

Machine-readable specifications

OpenAPI 3.1

Reference REST contract.

Download YAML ↓

AsyncAPI 3.0

Reference event contract.

Download YAML ↓

Postman

Collection for controlled integration testing.

Download JSON ↓