The HTTP API

One contract.Every registry operation.

Integrate public discovery and resolution, authenticated publication, and deliberate registry operations through the canonical v1 API. Request and response types come from Rust.

35 operations
camelCase JSON
URL-encoded DID paths

A closer lookA clear request. A defined response.

The HTTP API exposes explicit registry operations. Public reads and authenticated writes have distinct boundaries.

01Choose the operation
02Send the request
03Read the structured response

01 / access

Easy reads. Explicit authority.

Choose your registry base URL, then use the endpoint contract below. Each protected operation checks the authority relevant to that action.

Public reads
Resolve entries, inspect versions, and perform local discovery without a publication session.
Authenticated changes
SIWS is the concrete user authentication profile. Mutations require a session, relevant capability, and route-scoped idempotency.
Separate operator access
Deep health, administration, and federated discovery have protected access. Peer traffic uses signed federation envelopes.

02 / endpoint reference

The complete surface.

All 35 operations from the current OpenAPI v1 snapshot. WS denotes an HTTP GET upgraded to WebSocket.

Entries and history
Discovery
Attestations, reports, and bonds
Ownership transfer
Federation
Authentication
Health and operator controls
Events

Entries and history

POST/v1/entries
Entry created
Request
MarsEntry
Response
MarsEntry (201)
DELETE/v1/entries/{did}
Entry revoked
Request
—
Response
— (204)
GET/v1/entries/{did}
Latest entry
Request
—
Response
MarsEntry (200)
PUT/v1/entries/{did}
Entry updated
Request
MarsEntry
Response
MarsEntry (200)
GET/v1/entries/{did}/lineage
Canonical lineage summary; lineage is null when absent
Request
—
Response
EntryLineageResponse (200)
GET/v1/entries/{did}/versions
Bounded version page in stable newest-first sequence order
Request
—
Response
EntryVersionsResponse (200)
GET/v1/entries/{did}/versions/{version}
Specific entry version
Request
—
Response
MarsEntry (200)

Discovery

POST/v1/discover
Discovery results
Request
DiscoverRequest
Response
MarsQueryResult (200)
POST/v1/discover/federated
Deterministically merged local and signed peer results with bounded partial metadata
Request
MarsQuery
Response
FederatedDiscoveryResult (200)
POST/v1/discover/marsql
MARS-QL DISCOVER results
Request
MarsQlRequest
Response
MarsQueryResult (200)

Attestations, reports, and bonds

POST/v1/attestations
Verifies and separately stores a canonical OAS Verifiable Credential.
Request
AttestationRequest
Response
VerifiableAttestationRecord (201)
GET/v1/attestations/{did}
Verified attestations; expired and revoked omitted by default
Request
—
Response
VerifiableAttestationRecord[] (200)
GET/v1/bonds/{bond_id}
Bond record
Request
—
Response
Bond (200)
POST/v1/report
Records a report whose reporter is derived from Principal.
Request
ReportRequest
Response
ReportResponse (201)

Ownership transfer

GET/v1/transfers/offers/{offer_id}
Transfer offer
Request
—
Response
TransferOffer (200)
POST/v1/transfers/offers/{offer_id}/accept
Recipient-signed transferred entry
Request
TransferAcceptRequest
Response
MarsEntry (200)
POST/v1/transfers/offers/{offer_id}/decline
Declined transfer offer
Request
TransferDeclineRequest
Response
TransferOffer (200)
POST/v1/transfers/{did}/offers
Creates a signed, expiring offer without changing entry ownership.
Request
TransferOfferRequest
Response
TransferOffer (201)

Federation

POST/v1/federation/discover
Serves a typed MARS-QL query only after signed-envelope verification, replay protection, and active agreement authorization.
Request
SignedFederationEnvelope_FederatedDiscoveryRequest
Response
SignedFederationEnvelope_FederatedDiscoveryResponse (200)
GET/v1/federation/peers
Canonical federation peer list
Request
—
Response
FederationPeer[] (200)
PUT/v1/federation/peers/self
Principal-bound peer metadata
Request
FederationPeerUpdateRequest
Response
FederationPeer (200)
POST/v1/federation/sync
Returns local changes only after OAS service identity, JCS Ed25519 envelope, durable nonce, and active agreement verification.
Request
SignedFederationEnvelope_SyncRequest
Response
SignedFederationEnvelope_SyncResponse (200)
GET/v1/registries
Compatibility alias with the exact response body of GET /v1/federation/peers.
Request
—
Response
FederationPeer[] (200)

Authentication

POST/v1/auth/logout
Session revoked idempotently
Request
—
Response
— (204)
GET/v1/auth/session
Current SIWS identity
Request
—
Response
SiwsSessionResponse (200)
POST/v1/auth/siws/challenge
Single-use SIWS challenge
Request
SiwsChallengeRequest
Response
SiwsChallengeResponse (200)
POST/v1/auth/siws/verify
Verified identity and opaque MARS session
Request
SiwsVerifyRequest
Response
SiwsVerifyResponse (200)

Health and operator controls

POST/v1/admin/anchors/{intent_id}/abandon
Intent abandoned
Request
—
Response
AnchorControlResponse (200)
POST/v1/admin/anchors/{intent_id}/retry
Intent requeued
Request
—
Response
AnchorControlResponse (200)
POST/v1/admin/bonds
Registry-local bond provisioned
Request
BondProvisionRequest
Response
Bond (201)
GET/v1/admin/federation/peers
Protected durable peer cursor, breaker, lag, and quarantine status
Request
—
Response
FederationPeerStatus[] (200)
GET/v1/anchors/{did}
Returns a stable keyset page of durable provider-neutral anchor intents, immutable receipts, and the current registry projection.
Request
—
Response
AnchorListResponse (200)
GET/v1/health
Shallow service health
Request
—
Response
HealthResponse (200)
GET/v1/health/deep
Operator subsystem health; inspect the body status
Request
—
Response
DeepHealthResponse (200)

Events

WS/v1/ws
WebSocket protocol upgrade
Request
—
Response
— (101)

Federated discovery routes depend on configuration. Anchor operations expose staged intents and receipts; endpoint presence does not establish activated Sigil authority.