Federation discover
Serves a typed MARS-QL query only after signed-envelope verification, replay protection, and active agreement authorization.
Contract and client context
Operation: federation_discover · HTTP: POST /v1/federation/discover
Use an operator-supplied registry base URL. Request execution is disabled in this documentation explorer. Generated request snippets are templates, not signed or authorized submissions.
This endpoint authenticates a signed federation envelope against configured peers and keys. It is not an unsigned public mutation merely because the OpenAPI bearer security list is absent.
Exact operation definition
{
"description": "Serves a typed MARS-QL query only after signed-envelope verification, replay protection, and active agreement authorization.",
"operationId": "federation_discover",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignedFederationEnvelope_FederatedDiscoveryRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignedFederationEnvelope_FederatedDiscoveryResponse"
}
}
},
"description": "Signed peer discovery response"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Envelope signature, timestamp, nonce, or controller invalid"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Peer or agreement not authorized"
},
"413": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Signed federation body exceeds the explicit admission limit"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Federation rate limit exceeded"
}
},
"tags": [
"federation"
]
}Resolve schema references against the complete OpenAPI document. Standalone schemas and hashes are generated from the same checked-in source.
/v1/federation/discoverRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
JCS-canonical, detached Ed25519 envelope used for federation traffic.
The signature covers every field except signature, including the sender,
recipient, key controller, timestamp, nonce, request digest, and payload.
Request digests bind responses to the exact request they answer.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/federation/discover" \ -H "Content-Type: application/json" \ -d '{ "algorithm": "string", "keyId": "string", "kind": "sync_request", "nonce": "string", "payload": { "query": { "entryType": "AgentDefinition" } }, "recipientDid": "string", "requestDigest": "string", "senderDid": "string", "signature": "string", "timestamp": "2019-08-24T14:15:22Z", "version": "string" }'{ "algorithm": "string", "keyId": "string", "kind": "sync_request", "nonce": "string", "payload": { "result": { "cursor": "string", "entries": [ { "accessPolicy": null, "anchorState": "unanchored", "bondReference": null, "customMetadata": { "property1": null, "property2": null }, "description": "string", "entryDid": "string", "entryType": "AgentDefinition", "itemData": null, "itemDataHash": "string", "itemSchemaUri": "string", "lifecycleStatus": "draft", "lineageReference": null, "marsVersion": "string", "name": "string", "publishedAt": "2019-08-24T14:15:22Z", "publisherDid": "string", "relationships": [ { "label": "string", "relationshipType": "dependsOn", "targetDid": "string" } ], "semanticAnnotations": [ { "objectLiteral": "string", "objectUri": "string", "predicateUri": "string" } ], "sequence": 0, "serviceEndpoints": [ { "id": "string", "priority": 0, "properties": { "property1": null, "property2": null }, "type": "string", "url": "string" } ], "shardAssignment": "string", "signature": { "algorithm": "string", "created": "string", "keyId": "string", "value": "string" }, "tags": [ "string" ], "updatedAt": "2019-08-24T14:15:22Z", "verifiableAttestations": [ null ], "version": "string" } ], "hasMore": true, "totalCount": 0 } }, "recipientDid": "string", "requestDigest": "string", "senderDid": "string", "signature": "string", "timestamp": "2019-08-24T14:15:22Z", "version": "string"}