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 GuideView API Reference
VIEW ONLINE FIRSTOpenAPI/AsyncAPI/Postman are export artifacts; HTML is the primary developer journey.
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