{ "openapi": "3.0.0", "info": { "title": "Keymaster API", "version": "2.1.0", "description": "Documentation for Keymaster API" }, "components": { "schemas": { "EncryptedMnemonic": { "type": "object", "required": [ "salt", "iv", "data" ], "properties": { "salt": { "type": "string", "description": "Base64-encoded salt used for key derivation." }, "iv": { "type": "string", "description": "Base64-encoded initialization vector for AES-GCM encryption." }, "data": { "type": "string", "description": "Base64-encoded encrypted mnemonic." } } }, "WalletId": { "type": "object", "required": [ "did", "account", "index" ], "properties": { "did": { "type": "string" }, "account": { "type": "integer" }, "index": { "type": "integer" }, "held": { "type": "array", "items": { "type": "string" } }, "owned": { "type": "array", "items": { "type": "string" } }, "dmail": { "type": "object", "additionalProperties": true }, "notices": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "Wallet": { "type": "object", "required": [ "version", "seed", "counter", "ids" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "seed": { "type": "object", "required": [ "mnemonicEnc" ], "properties": { "mnemonicEnc": { "$ref": "#/components/schemas/EncryptedMnemonic" } } }, "counter": { "type": "integer" }, "ids": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/WalletId" } }, "current": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": true }, "EncryptedWallet": { "type": "object", "required": [ "version", "seed", "enc" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "seed": { "type": "object", "required": [ "mnemonicEnc" ], "properties": { "mnemonicEnc": { "$ref": "#/components/schemas/EncryptedMnemonic" } } }, "enc": { "type": "string", "description": "Encrypted wallet data (IDs, names, etc.)." } } }, "LegacyWallet": { "type": "object", "description": "Legacy v0 wallet accepted for automatic migration to v1.", "required": [ "seed", "counter", "ids" ], "properties": { "version": { "type": "integer", "enum": [ 0 ] }, "seed": { "type": "object", "required": [ "mnemonic", "hdkey" ], "properties": { "mnemonic": { "type": "string" }, "hdkey": { "type": "object", "required": [ "xpriv", "xpub" ], "properties": { "xpriv": { "type": "string" }, "xpub": { "type": "string" } } } } }, "counter": { "type": "integer" }, "ids": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/WalletId" } }, "current": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": true }, "StoredWallet": { "oneOf": [ { "$ref": "#/components/schemas/Wallet" }, { "$ref": "#/components/schemas/EncryptedWallet" }, { "$ref": "#/components/schemas/LegacyWallet" } ] } } }, "servers": [ { "url": "http://localhost:4226/api/v1", "description": "Local Keymaster" } ], "paths": { "/ready": { "get": { "summary": "Check if the Keymaster service is ready.", "description": "Returns a JSON object indicating the readiness status of the Keymaster service.", "responses": { "200": { "description": "Keymaster service readiness status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/registries": { "get": { "summary": "List the available registries.", "responses": { "200": { "description": "A list of available registry names.", "content": { "application/json": { "schema": { "type": "object", "properties": { "registries": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/wallet": { "get": { "summary": "Retrieve the current wallet.", "responses": { "200": { "description": "The wallet object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Wallet" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "put": { "summary": "Save the wallet.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/StoredWallet" } }, "required": [ "wallet" ] } } } }, "responses": { "200": { "description": "Indicates whether the wallet was saved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/wallet/new": { "post": { "summary": "Create a new wallet.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mnemonic": { "type": "string", "description": "12 words separated by a space (optional)." }, "overwrite": { "type": "boolean", "description": "Whether to overwrite the existing wallet.", "default": false } } } } } }, "responses": { "200": { "description": "The newly created wallet object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Wallet" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/wallet/backup": { "post": { "summary": "Create a backup of the current wallet.", "responses": { "200": { "description": "The DID of the wallet backup.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "string", "description": "The DID associated with the wallet backup." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/wallet/recover": { "post": { "summary": "Recover the wallet from an existing backup.", "responses": { "200": { "description": "The recovered wallet object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Wallet" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/wallet/check": { "post": { "summary": "Check the integrity of the wallet.", "responses": { "200": { "description": "The check result object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "check": { "type": "object", "properties": { "checked": { "type": "integer", "description": "Number of IDs checked." }, "invalid": { "type": "integer", "description": "Number of IDs found invalid." }, "deleted": { "type": "integer", "description": "Number of IDs found deleted or deactivated." } } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/wallet/fix": { "post": { "summary": "Fix the wallet by removing invalid or deactivated entries.", "responses": { "200": { "description": "The fix result object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fix": { "type": "object", "properties": { "idsRemoved": { "type": "integer" }, "ownedRemoved": { "type": "integer" }, "heldRemoved": { "type": "integer" }, "namesRemoved": { "type": "integer" } } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/wallet/mnemonic": { "get": { "summary": "Decrypt and retrieve the wallet's mnemonic phrase.", "responses": { "200": { "description": "The mnemonic phrase.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mnemonic": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/export/wallet/encrypted": { "get": { "summary": "Export the wallet in encrypted form.", "description": "Returns the wallet in its encrypted format, which includes the encrypted mnemonic and encrypted wallet data. This format is secure for storage or backup purposes.\n", "responses": { "200": { "description": "The encrypted wallet object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/EncryptedWallet" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/did/{id}": { "get": { "summary": "Resolve a DID Document.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID or name to resolve." }, { "in": "query", "name": "versionTime", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Timestamp to return the state of the DID as of this specific time (RFC3339/ISO8601 format).\n" }, { "in": "query", "name": "versionSequence", "required": false, "schema": { "type": "integer" }, "description": "Specific version of the DID Document to retrieve. Increments each time an `update` or `delete` operation occurs.\n" }, { "in": "query", "name": "confirm", "required": false, "schema": { "type": "boolean" }, "description": "If true, excludes later events until they are confirmed by the DID's native registry.\n" }, { "in": "query", "name": "verify", "required": false, "schema": { "type": "boolean" }, "description": "If true, verifies the signature(s) of the DID operation(s) before returning the DID Document. If a signature is invalid, an error is thrown.\n" } ], "responses": { "200": { "description": "Successfully resolved the DID Document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "docs": { "type": "object", "description": "The resolved DID Document and its metadata.", "properties": { "didDocument": { "type": "object", "description": "The actual DID Document, if it exists.", "properties": { "@context": { "type": "array", "items": { "type": "string" }, "description": "DID Document contexts." }, "id": { "type": "string", "description": "The DID this document represents." }, "controller": { "type": "string", "description": "The DID or entity controlling this asset (if applicable)." }, "verificationMethod": { "type": "array", "description": "An array of verification methods (keys).", "items": { "type": "object", "properties": { "id": { "type": "string" }, "controller": { "type": "string" }, "type": { "type": "string" }, "publicKeyJwk": { "type": "object", "description": "Public key in JWK format." } } } }, "authentication": { "type": "array", "items": { "type": "string" }, "description": "Verification method references used for authentication." } } }, "didDocumentMetadata": { "type": "object", "description": "Metadata about the DID Document.", "properties": { "created": { "type": "string", "format": "date-time" }, "updated": { "type": "string", "format": "date-time" }, "deleted": { "type": "string", "format": "date-time" }, "version": { "type": "string" }, "versionId": { "type": "string", "description": "A CID or similar identifier for the version." }, "canonicalId": { "type": "string" }, "confirmed": { "type": "boolean" }, "deactivated": { "type": "boolean" }, "isOwned": { "type": "boolean", "description": "Whether the resolved DID is controlled by an identity in the current wallet." }, "timestamp": { "type": "object", "description": "Optional blockchain timestamp bounds for the current operation." } } }, "didDocumentData": { "description": "Arbitrary JSON data attached to the DID (only present for assets)." }, "didResolutionMetadata": { "type": "object", "description": "Metadata describing the resolution result.", "properties": { "retrieved": { "type": "string", "format": "date-time" }, "error": { "type": "string", "enum": [ "invalidDid", "notFound" ] } } }, "mdip": { "type": "object", "description": "MDIP-specific metadata fields.", "properties": { "type": { "type": "string", "enum": [ "agent", "asset" ] }, "registry": { "type": "string", "enum": [ "local", "hyperswarm", "TESS", "TBTC", "TFTC", "Signet", "Signet-Inscription", "BTC-Inscription" ] }, "version": { "type": "integer" }, "prefix": { "type": "string" }, "validUntil": { "type": "string", "format": "date-time" }, "created": { "type": "string" } } } } } } } } } }, "404": { "description": "DID not found or cannot be resolved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Revoke a DID.", "description": "Removes an existing DID from the system, effectively revoking it.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID to revoke." } ], "responses": { "200": { "description": "Indicates whether the DID was successfully revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the DID was successfully revoked, otherwise false." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/ids/current": { "get": { "summary": "Retrieve the current ID name.", "responses": { "200": { "description": "The current ID name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "current": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "put": { "summary": "Set the current ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the ID to set as current." } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Indicates if the current ID was successfully updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid name or unknown ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/ids": { "get": { "summary": "List all ID names in the wallet.", "responses": { "200": { "description": "A list of ID names.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Create a new ID in the wallet.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the new ID." }, "options": { "type": "object", "description": "Optional parameters.", "properties": { "registry": { "type": "string", "enum": [ "local", "hyperswarm", "TBTC", "TFTC" ] } } } } } } } }, "responses": { "200": { "description": "The DID created for the new ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "A DID string identifying the new ID." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/ids/{id}": { "get": { "summary": "Resolve an ID to a DID Document.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The name or DID to resolve." } ], "responses": { "200": { "description": "The resolved DID Document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "docs": { "type": "object", "description": "The DID Document and associated metadata." } } } } } }, "404": { "description": "ID not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Remove an existing ID from the wallet.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The name of the ID to remove." } ], "responses": { "200": { "description": "Indicates whether the ID was successfully removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid ID or request error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/ids/{id}/rename": { "post": { "summary": "Rename an existing ID in the wallet.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The current name of the ID to be renamed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the ID." } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Indicates whether the rename was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid ID or the new name is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/ids/{id}/backup": { "post": { "summary": "Backup the specified ID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID name or DID to back up." } ], "responses": { "200": { "description": "Indicates whether the backup operation succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid ID or request error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/ids/{id}/recover": { "post": { "summary": "Recover an existing ID from a backup reference.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID name or DID to recover." } ], "responses": { "200": { "description": "The ID name that was recovered and is now current.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recovered": { "type": "string" } } } } } }, "404": { "description": "Backup DID not found or invalid ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Other error when recovering the ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/names": { "get": { "summary": "List all name-to-DID mappings in the wallet.", "responses": { "200": { "description": "A list of all name-to-DID mappings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "names": { "type": "object", "additionalProperties": { "type": "string" }, "description": "An object where each key is a name, and each value is the associated DID." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Add a new name-to-DID mapping.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The human-readable name to associate with the DID." }, "did": { "type": "string", "description": "The DID that this name should refer to." } }, "required": [ "name", "did" ] } } } }, "responses": { "200": { "description": "Indicates whether the mapping was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/names/{name}": { "get": { "summary": "Retrieve the DID associated with a specific name.", "description": "Returns the DID for the provided human-readable name, if it exists.", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name for which you want the associated DID." } ], "responses": { "200": { "description": "The DID associated with the requested name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "404": { "description": "The requested name was not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Remove an existing name-to-DID mapping.", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name whose mapping should be removed." } ], "responses": { "200": { "description": "Indicates whether the mapping was successfully removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "The requested name was invalid or could not be removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/challenge": { "get": { "summary": "Create a default challenge DID with no parameters.", "responses": { "200": { "description": "A DID representing the newly created challenge.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID for the newly created challenge." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Create a challenge DID with custom data or options.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge": { "type": "object", "description": "Arbitrary challenge data." }, "options": { "type": "object", "description": "Additional options.", "properties": { "registry": { "type": "string", "enum": [ "local", "hyperswarm", "TBTC", "TFTC" ] }, "validUntil": { "type": "string", "format": "date-time" } } } } } } } }, "responses": { "200": { "description": "DID representing the newly created challenge.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "400": { "description": "Bad request (invalid parameters).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/response": { "post": { "summary": "Create a response to an existing challenge DID.", "description": "Accepts a challenge DID (the DID of a previously created challenge) and an `options` object, then returns a new DID containing the response. Internally, the Keymaster finds matching credentials and bundles them into verifiable presentations. The response is encrypted for the original challenge's controller and stored as a new asset DID.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge": { "type": "string", "description": "DID of the challenge to respond to." }, "options": { "type": "object", "description": "Additional parameters controlling how the response is created and stored.", "properties": { "registry": { "type": "string", "description": "The registry where the new response DID will be created (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Expiration time for the response DID. If omitted, defaults to 1 hour from now." }, "retries": { "type": "integer", "description": "How many times to retry resolving the challenge DID if it is not immediately resolvable.", "default": 0 }, "delay": { "type": "integer", "description": "Milliseconds to wait between retries.", "default": 1000 }, "encryptForSender": { "type": "boolean", "description": "Whether to include an encrypted copy for the sender (the responding party). Defaults to true." }, "includeHash": { "type": "boolean", "description": "Whether to embed a hash of the plaintext in the stored asset. Defaults to false." }, "controller": { "type": "string", "description": "A specific ID or DID to act as the controller of the newly created asset. If not set, the current ID is used." } } } } } } } }, "responses": { "200": { "description": "A DID containing the response to the challenge.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID of the newly created response asset." } } } } } }, "400": { "description": "Invalid input (e.g., challenge not found, or required parameters missing).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/response/verify": { "post": { "summary": "Verify a response to a challenge.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string", "description": "DID of the challenge response asset to verify." }, "options": { "type": "object", "description": "Additional verification parameters.", "properties": { "retries": { "type": "integer", "description": "How many times to retry resolving the response DID if initially not found.", "default": 0 }, "delay": { "type": "integer", "description": "How many milliseconds to wait between resolution retries.", "default": 1000 }, "publish": { "type": "boolean", "description": "Publish challenge receipts when the response matches.", "default": true }, "versionTime": { "type": "string", "format": "date-time", "description": "If provided, attempts to resolve the response DID as of a specific point in time." }, "versionSequence": { "type": "integer", "description": "If provided, attempts to resolve the response DID at a specific version." }, "confirm": { "type": "boolean", "description": "If true, only returns the DID if it is fully confirmed on its registry." }, "verify": { "type": "boolean", "description": "If true, verifies the signature(s) of the response operation(s) before returning the DID Document." } } } } } } } }, "responses": { "200": { "description": "The result of the verification process.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verify": { "type": "object", "description": "A detailed verification result.", "properties": { "challenge": { "type": "string", "description": "The DID of the original challenge." }, "credentials": { "type": "array", "items": { "type": "object" }, "description": "Each credential pair (vc, vp) the response included." }, "match": { "type": "boolean", "description": "true if the response satisfies all challenge requirements, otherwise `false`." }, "vps": { "type": "array", "description": "Any verifiable presentations that passed verification.", "items": { "type": "object" } }, "responder": { "type": "string", "description": "The DID (controller) of the responder." } } } } } } } }, "400": { "description": "Verification failed or request was invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/response/receipts": { "post": { "summary": "Publish challenge usage receipts for a verified response.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "response" ], "properties": { "response": { "type": "string", "description": "DID of the verified challenge response." }, "options": { "type": "object", "properties": { "verification": { "type": "object", "description": "Existing verification result. Otherwise, the response is verified first." }, "retries": { "type": "integer" }, "delay": { "type": "integer" }, "registry": { "type": "string" }, "validUntil": { "type": "string", "format": "date-time" }, "name": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "DIDs of the published challenge receipts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dids": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "The response or options were invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/groups": { "get": { "summary": "List all group DIDs owned by (or associated with) a specific ID.", "parameters": [ { "in": "query", "name": "owner", "required": false, "schema": { "type": "string" }, "description": "The name or DID of the owner ID for which to list groups." } ], "responses": { "200": { "description": "An array of group DIDs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Create a new group asset (DID).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The human-readable name of the group." }, "options": { "type": "object", "description": "Additional parameters for creating the group.", "properties": { "members": { "type": "array", "items": { "type": "string" }, "description": "An array of member DIDs or sub-group DIDs to include initially." }, "registry": { "type": "string", "description": "The registry in which to create the group DID (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Timestamp indicating when this group asset should expire (optional)." }, "retries": { "type": "integer", "default": 0, "description": "How many times to retry DID creation if immediate creation fails." }, "delay": { "type": "integer", "default": 1000, "description": "Delay in milliseconds between retries." }, "encryptForSender": { "type": "boolean", "description": "Whether to include an encrypted copy for the current ID. Defaults to true if encryption is used." }, "includeHash": { "type": "boolean", "description": "Whether to embed a hash of the group's data in the created asset. Defaults to false." }, "controller": { "type": "string", "description": "An ID or DID that should be set as the controller of this new group asset. Defaults to the current ID if omitted." } } } } } } } }, "responses": { "200": { "description": "The DID representing the newly created group.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/groups/{name}": { "get": { "summary": "Retrieve an existing group.", "description": "Returns the stored group object (including its name and members) for the given group DID or name.", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name or DID of the group to retrieve." } ], "responses": { "200": { "description": "The group object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "type": "object", "properties": { "name": { "type": "string" }, "members": { "type": "array", "items": { "type": "string" } } } } } } } } }, "404": { "description": "The requested group was not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/groups/{name}/add": { "post": { "summary": "Add a member to an existing group.", "description": "Adds a DID (or group) as a member of the specified group.", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name or DID of the group to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "string", "description": "The DID (or group DID) to add as a member." } }, "required": [ "member" ] } } } }, "responses": { "200": { "description": "Indicates whether the member was successfully added.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/groups/{name}/remove": { "post": { "summary": "Remove a member from an existing group.", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name or DID of the group to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "string", "description": "The DID (or group DID) to remove from the group." } }, "required": [ "member" ] } } } }, "responses": { "200": { "description": "Indicates whether the member was successfully removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/groups/{name}/test": { "post": { "summary": "Test membership in a group.", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name or DID of the group to test." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "string", "description": "The DID or group DID to check for membership." } } } } } }, "responses": { "200": { "description": "The result of the membership test.", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean", "description": "true if the member is found in the group, otherwise `false`." } } } } } }, "400": { "description": "Invalid input or request could not be processed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/schemas": { "get": { "summary": "List all schema DIDs owned by (or associated with) a specific ID.", "parameters": [ { "in": "query", "name": "owner", "required": false, "schema": { "type": "string" }, "description": "The name or DID of the owner whose schemas should be listed." } ], "responses": { "200": { "description": "A list of schema DIDs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Create a new schema.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "object", "description": "A valid JSON Schema to be stored." }, "options": { "type": "object", "description": "Additional creation parameters.", "properties": { "registry": { "type": "string", "description": "The registry in which to create the schema DID (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Optional expiration date/time for ephemeral schemas." } } } } } } } }, "responses": { "200": { "description": "The DID representing the newly created schema.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/schemas/{id}": { "get": { "summary": "Retrieve a stored schema.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The name or DID of the schema to retrieve." } ], "responses": { "200": { "description": "The JSON Schema object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "object", "description": "The retrieved JSON Schema." } } } } } }, "404": { "description": "Schema not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "put": { "summary": "Update an existing schema.", "description": "Replaces the schema (if valid) associated with the given DID or name. This operation will preserve the same DID while storing an updated schema in the underlying asset data.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The name or DID of the schema to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "object", "description": "The new JSON Schema to store." } } } } } }, "responses": { "200": { "description": "Indicates whether the update was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/schemas/{id}/test": { "post": { "summary": "Test if a DID or name refers to a valid schema.", "description": "Checks whether the given DID or name refers to an asset containing a valid JSON Schema. Returns true if it's a recognized valid schema, otherwise `false`.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The name or DID of the schema to test." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No required body parameters (reserved for future use)." } } } }, "responses": { "200": { "description": "Whether the asset is recognized as a valid schema.", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean", "description": "true if the asset is a valid schema, otherwise `false`." } } } } } }, "400": { "description": "Invalid DID/name or request processing error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/agents/{id}/test": { "post": { "summary": "Check whether the given ID (or DID) is an agent.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID name or DID to test." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No body required for this endpoint." } } } }, "responses": { "200": { "description": "Whether the specified DID is recognized as an agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean", "description": "true if the DID is an agent. Otherwise, `false`." } } } } } }, "400": { "description": "Invalid request or DID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/credentials/bind": { "post": { "summary": "Prepare (bind) a credential without issuing it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "The schema DID or name to which this credential conforms." }, "subject": { "type": "string", "description": "The subject DID (or name) for whom this credential is bound." }, "options": { "type": "object", "description": "Optional parameters for credential creation.", "properties": { "credential": { "type": "object", "description": "A pre-built credential object to embed. If omitted, a default is generated from the schema." }, "validFrom": { "type": "string", "format": "date-time", "description": "The date/time the credential becomes valid. Defaults to the current time if omitted." }, "validUntil": { "type": "string", "format": "date-time", "description": "The date/time the credential expires. Omit for an open-ended credential." } } } } } } } }, "responses": { "200": { "description": "The prepared credential object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "description": "The bound credential." } } } } } }, "400": { "description": "Invalid parameters or schema/subject issues.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/credentials/held": { "get": { "summary": "List all credentials currently held by the active ID.", "responses": { "200": { "description": "The list of held credential DIDs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "held": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Accept a credential into the \"held\" list of the current ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The credential DID to hold." } }, "required": [ "did" ] } } } }, "responses": { "200": { "description": "Whether the acceptance was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid DID or failure to accept the credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/credentials/held/{did}": { "get": { "summary": "Retrieve (decrypt) a held credential.", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The credential DID to retrieve." } ], "responses": { "200": { "description": "The decrypted credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "description": "The credential contents (VC)." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Remove a credential from the \"held\" list.", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The credential DID to remove from holdings." } ], "responses": { "200": { "description": "Whether the removal was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid DID or request error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/credentials/held/{did}/publish": { "post": { "summary": "Publish a held credential publicly.", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The credential DID to publish from the holder's wallet." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": "object", "description": "Additional parameters controlling the publication.", "properties": { "reveal": { "type": "boolean", "default": false, "description": "Whether to include the full credential data or just a reference." } } } } } } } }, "responses": { "200": { "description": "Indicates whether the publish operation was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "object", "description": "The updated DID Document or partial success info." } } } } } }, "400": { "description": "Credential not held by this ID or invalid request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/credentials/held/{did}/unpublish": { "post": { "summary": "Remove a published credential from the holder’s DID Document manifest.", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The credential DID to unpublish." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No additional parameters by default." } } } }, "responses": { "200": { "description": "Indicates whether the unpublish operation was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "string", "description": "Status message or success flag." } } } } } }, "400": { "description": "Credential not found in the DID Document's manifest or invalid request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/credentials/issued": { "get": { "summary": "List all credentials issued by the current ID.", "responses": { "200": { "description": "The list of credential DIDs issued by the current ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "issued": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Issue a new credential.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "description": "A valid credential object. If omitted, `options.schema` and `options.subject` can be used to generate one." }, "options": { "type": "object", "description": "Additional issuance parameters.", "properties": { "schema": { "type": "string", "description": "DID or name of the schema, used if `credential` is not fully provided." }, "subject": { "type": "string", "description": "DID or name of the subject for which the credential is being issued." }, "registry": { "type": "string", "description": "Where to create the credential DID (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Expiration for the credential DID, if ephemeral." }, "retries": { "type": "integer", "default": 0, "description": "Retries for DID creation or resolution if needed." }, "delay": { "type": "integer", "default": 1000, "description": "Delay between retries in milliseconds." }, "encryptForSender": { "type": "boolean", "description": "Include an encrypted copy for the issuer. Defaults to true." }, "includeHash": { "type": "boolean", "description": "Embed a hash of the credential in the asset. Defaults to false." }, "controller": { "type": "string", "description": "Specific ID or DID to set as the controller of the new asset. Defaults to the issuer’s current ID." } } } } } } } }, "responses": { "200": { "description": "The DID of the newly issued credential asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "400": { "description": "Invalid credential data or issuance error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/credentials/issued/{did}": { "get": { "summary": "Retrieve an issued credential by DID.", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The DID of the issued credential to retrieve." } ], "responses": { "200": { "description": "The decrypted credential object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "description": "The credential data." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Update an existing issued credential.", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The DID of the issued credential to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "description": "The new credential data to store." } }, "required": [ "credential" ] } } } }, "responses": { "200": { "description": "Whether the update was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid credential or operation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Revoke a previously issued credential.", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The DID of the credential to revoke." } ], "responses": { "200": { "description": "Whether the revocation (delete) operation was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid DID or revocation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/credentials/issued/{did}/send": { "post": { "summary": "Send an issued credential to its subject.", "description": "Creates a notice to deliver the specified issued credential to its credentialSubject. The notice is created in the ephemeral registry and is valid for 7 days by default. Returns null if the credential cannot be found.\n", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The DID of the issued credential to send." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": "object", "properties": { "registry": { "type": "string" }, "controller": { "type": "string" }, "validUntil": { "type": "string", "format": "date-time" }, "name": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "The DID of the created notice, or null if the credential was not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "nullable": true, "description": "The DID of the notice created to deliver the credential, or null if the credential doesn't exist." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/keys/rotate": { "post": { "summary": "Rotate the current ID's keys.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No options required. Key rotation applies to the current ID." } } } }, "responses": { "200": { "description": "Indicates whether key rotation was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/keys/encrypt/message": { "post": { "summary": "Encrypt a plaintext message into a DID asset.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "description": "The plaintext message to encrypt." }, "receiver": { "type": "string", "description": "The DID (or name) of the intended recipient." }, "options": { "type": "object", "description": "Additional encryption/creation parameters.", "properties": { "registry": { "type": "string", "description": "Where to create the asset DID (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "When this asset should expire. If omitted, it is permanent unless manually revoked." }, "retries": { "type": "integer", "default": 0, "description": "Number of times to retry the operation if not immediately successful." }, "delay": { "type": "integer", "default": 1000, "description": "Milliseconds to wait between retries." }, "encryptForSender": { "type": "boolean", "default": true, "description": "Whether to include an encrypted copy for the sender." }, "includeHash": { "type": "boolean", "default": false, "description": "Whether to embed a hash of the plaintext in the asset." }, "controller": { "type": "string", "description": "Which ID or DID should control this newly created asset. Defaults to the current ID." } } } } } } } }, "responses": { "200": { "description": "The DID of the newly created encrypted asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "500": { "description": "Internal server error (encryption or wallet issue).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/keys/decrypt/message": { "post": { "summary": "Decrypt an encrypted message asset by DID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID representing the encrypted asset." } }, "required": [ "did" ] } } } }, "responses": { "200": { "description": "The decrypted plaintext message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The original message that was encrypted." } } } } } }, "500": { "description": "Internal server error (e.g., no matching key found to decrypt).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/keys/encrypt/json": { "post": { "summary": "Encrypt a JSON object into a DID asset.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "json": { "type": "object", "description": "The JSON object to be encrypted." }, "receiver": { "type": "string", "description": "The DID (or name) of the intended recipient." }, "options": { "type": "object", "description": "Additional encryption/creation parameters (same fields as `/keys/encrypt/message`).", "properties": { "registry": { "type": "string" }, "validUntil": { "type": "string", "format": "date-time" }, "retries": { "type": "integer", "default": 0 }, "delay": { "type": "integer", "default": 1000 }, "encryptForSender": { "type": "boolean", "default": true }, "includeHash": { "type": "boolean", "default": false }, "controller": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "The DID of the encrypted JSON asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "500": { "description": "Internal server error (e.g., encryption or wallet issue).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/keys/decrypt/json": { "post": { "summary": "Decrypt a JSON asset by DID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID representing the encrypted JSON asset." } }, "required": [ "did" ] } } } }, "responses": { "200": { "description": "The decrypted JSON object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "json": { "type": "object", "description": "The original JSON data that was encrypted." } } } } } }, "500": { "description": "Internal server error (no matching key found to decrypt or other error).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/keys/sign": { "post": { "summary": "Add a signature to a JSON object using the current ID's keys.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contents": { "type": "string", "description": "A JSON string representing the data to be signed." } }, "required": [ "contents" ] } } } }, "responses": { "200": { "description": "The signed object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "signed": { "type": "object", "description": "The original JSON plus a `signature` block." } } } } } }, "500": { "description": "Internal server error (e.g., signing failure).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/keys/verify": { "post": { "summary": "Verify a JSON object's signature.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "json": { "type": "object", "description": "The signed JSON object to verify, which must include a `signature` property." } }, "required": [ "json" ] } } } }, "responses": { "200": { "description": "Whether the signature is valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the signature is valid. Otherwise, `false`." } } } } } }, "500": { "description": "Internal server error (verification failure or unexpected error).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/schemas/{id}/template": { "post": { "summary": "Generate a JSON template from a schema.", "description": "Creates a JSON template object based on the specified schema. The template will include placeholder values that conform to the schema's structure and constraints.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The name or DID of the schema from which to generate a template." } ], "responses": { "200": { "description": "The generated JSON template object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "object", "description": "A skeleton object containing placeholder values that conform to the schema." } } } } } }, "500": { "description": "Internal server error (e.g., invalid schema format or processing error).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/assets": { "post": { "summary": "Create a new asset DID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Arbitrary data to store in this asset." }, "options": { "type": "object", "description": "Additional creation parameters.", "properties": { "registry": { "type": "string", "description": "Where to create the asset DID (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Expiration date/time for an ephemeral asset. Omit for a permanent asset." }, "controller": { "type": "string", "description": "Specific ID or DID to act as the asset’s controller. Defaults to the current ID." }, "name": { "type": "string", "description": "A human-readable name for the asset." } } } } } } } }, "responses": { "200": { "description": "The DID of the newly created asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "500": { "description": "Internal server error (e.g., invalid parameters or wallet error).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "get": { "summary": "List all asset DIDs owned by the current ID.", "responses": { "200": { "description": "A list of asset DIDs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/assets/{id}": { "get": { "summary": "Resolve (retrieve) an asset by DID or name.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The asset name or DID to resolve." } ], "responses": { "200": { "description": "The resolved asset data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "object", "description": "The `didDocumentData` for the asset, or null if not found." } } } } } }, "404": { "description": "Asset not found or is deactivated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "put": { "summary": "Update an existing asset.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The asset DID or name to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "The new data to store in this asset's DID Document." } } } } } }, "responses": { "200": { "description": "Indicates whether the update was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/assets/{id}/transfer": { "post": { "summary": "Transfer ownership of an asset.", "description": "Transfers the ownership of the specified asset (identified by its DID or name) to a new controller.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the asset to transfer." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "controller": { "type": "string", "description": "The DID of the new controller to transfer ownership to." } }, "required": [ "controller" ] } } } }, "responses": { "200": { "description": "Indicates whether the transfer was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the transfer was successful, otherwise `false`." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/assets/{id}/clone": { "post": { "summary": "Clone an existing asset.", "description": "Creates a new asset by cloning the data of an existing asset identified by its DID or name. The cloned asset will include a reference to the original asset in its metadata.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the asset to clone." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": "object", "description": "Additional parameters for cloning the asset.", "properties": { "registry": { "type": "string", "description": "The registry in which to create the cloned asset (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Expiration timestamp for the cloned asset." } } } } } } } }, "responses": { "200": { "description": "The DID of the newly created cloned asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID of the cloned asset." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/templates/poll": { "get": { "summary": "Retrieve a boilerplate poll template.", "responses": { "200": { "description": "The default poll template object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "object", "properties": { "type": { "type": "string" }, "version": { "type": "integer" }, "description": { "type": "string" }, "roster": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "deadline": { "type": "string", "format": "date-time" } } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/polls": { "get": { "summary": "List polls owned by (or associated with) a given ID.", "parameters": [ { "in": "query", "name": "owner", "required": false, "schema": { "type": "string" }, "description": "The name or DID of the owner ID to list polls for." } ], "responses": { "200": { "description": "A list of poll DIDs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "polls": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Create a new poll.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "poll": { "type": "object", "description": "The poll definition containing the required fields.", "properties": { "type": { "type": "string", "enum": [ "poll" ], "default": "poll", "description": "Must be \"poll\"." }, "version": { "type": "integer", "default": 1, "description": "Must be 1 (only version 1 is supported)." }, "description": { "type": "string", "description": "A short description or question for the poll." }, "roster": { "type": "string", "description": "The DID or name of a group defining who is eligible to vote." }, "options": { "type": "array", "description": "A list of possible choices for the poll (at least 2, up to 10).", "minItems": 2, "maxItems": 10, "items": { "type": "string" } }, "deadline": { "type": "string", "format": "date-time", "description": "The date-time by which the poll closes (must be in the future)." } }, "required": [ "type", "version", "description", "roster", "options", "deadline" ] }, "options": { "type": "object", "description": "Additional parameters for poll creation.", "properties": { "registry": { "type": "string", "description": "Where to create the poll DID (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Expiration timestamp for the poll DID itself (not the poll’s internal deadline)." }, "retries": { "type": "integer", "default": 0, "description": "Number of times to retry poll creation if it fails initially." }, "delay": { "type": "integer", "default": 1000, "description": "Delay in milliseconds between retries." }, "encryptForSender": { "type": "boolean", "default": true, "description": "Include an encrypted copy for the poll creator if encryption is used." }, "includeHash": { "type": "boolean", "default": false, "description": "Whether to embed a hash of the poll in the DID asset." }, "controller": { "type": "string", "description": "The ID/DID that should own/control this poll. Defaults to the current ID if omitted." } } } } } } } }, "responses": { "200": { "description": "The DID representing the newly created poll.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/polls/{poll}": { "get": { "summary": "Retrieve the raw poll data by DID or name.", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the poll to retrieve." } ], "responses": { "200": { "description": "The poll object (if found).", "content": { "application/json": { "schema": { "type": "object", "properties": { "poll": { "type": "object", "description": "The poll data (type, version, options, roster, ballots, etc.)." } } } } } }, "500": { "description": "Internal server error or poll not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/polls/{poll}/test": { "get": { "summary": "Check if a DID or name refers to a valid poll.", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the poll to test." } ], "responses": { "200": { "description": "Indicates whether the asset is recognized as a valid poll.", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean", "description": "true if valid poll, otherwise `false`." } } } } } }, "500": { "description": "Internal server error (e.g., resolution error).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/polls/{poll}/view": { "get": { "summary": "View detailed poll information, including results if the caller is the poll owner.", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the poll to view." } ], "responses": { "200": { "description": "The poll view object, including voting status and (if owner) results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "poll": { "type": "object", "description": "Contains information about eligibility, results, etc." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/polls/{poll}/vote": { "post": { "summary": "Cast a vote in a poll.", "description": "Casts a vote in the specified poll. The vote is recorded as a ballot DID, which should be submitted to the poll owner.\n", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the poll to vote in." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vote": { "type": "integer", "description": "The numerical option index (1-based). Use 0 or set `spoil` in options to cast a spoiled ballot." }, "options": { "type": "object", "description": "Additional vote parameters.", "properties": { "spoil": { "type": "boolean", "default": false, "description": "If true, casts a spoiled ballot (vote=0)." }, "registry": { "type": "string", "description": "Where to create the ballot DID (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Expiration for the ballot DID, if ephemeral." }, "retries": { "type": "integer", "default": 0 }, "delay": { "type": "integer", "default": 1000 }, "encryptForSender": { "type": "boolean", "default": false, "description": "Whether to store an encrypted copy for the voter. Typically false for a secret ballot." }, "includeHash": { "type": "boolean", "default": false }, "controller": { "type": "string", "description": "Which ID or DID to assign as the ballot’s controller. Defaults to the poll's owner, but usually not changed here." } } } }, "required": [ "vote" ] } } } }, "responses": { "200": { "description": "The DID representing the newly created ballot (to be submitted to the poll owner).", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "500": { "description": "Internal server error (e.g., poll not valid, or wallet issue).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/polls/update": { "put": { "summary": "Record a received ballot in the poll.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ballot": { "type": "string", "description": "The DID of the ballot to record in the poll." } }, "required": [ "ballot" ] } } } }, "responses": { "200": { "description": "Indicates whether the ballot was successfully recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/polls/{poll}/publish": { "post": { "summary": "Publish final poll results to the poll’s DID Document.", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the poll to publish." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": "object", "description": "Publication parameters.", "properties": { "reveal": { "type": "boolean", "default": false, "description": "If true, includes all ballots. If false, only the summary is published." } } } } } } } }, "responses": { "200": { "description": "Indicates whether the publish operation was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "object", "description": "Typically the updated poll object or success indication." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/polls/{poll}/unpublish": { "post": { "summary": "Remove previously published poll results from the poll's DID Document.", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the poll to unpublish." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No additional parameters, unless needed for future expansions." } } } }, "responses": { "200": { "description": "Indicates whether the unpublish operation was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error or invalid poll ownership.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/images": { "post": { "summary": "Upload an image and create a DID for it.", "description": "Uploads an image as binary data and creates a DID for it. Additional options can be passed via the `X-Options` header.\n", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "description": "The image data to store as a DID asset." }, "parameters": [ { "in": "header", "name": "X-Options", "required": false, "schema": { "type": "string", "description": "A JSON string containing additional options for the image creation process. Example: `{\"registry\":\"local\",\"validUntil\":\"2025-12-31T23:59:59Z\"}`\n" } } ], "responses": { "200": { "description": "The DID created for the uploaded image.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID representing the uploaded image." } } } } } }, "500": { "description": "Internal server error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/images/{id}": { "put": { "summary": "Update an existing image.", "description": "Updates the binary data of an existing image identified by its DID.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the image to update." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "description": "The new image data to replace the existing one." }, "responses": { "200": { "description": "Indicates whether the update was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the update was successful, otherwise `false`." } } } } } }, "500": { "description": "Internal server error.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "get": { "summary": "Retrieve an image by its DID.", "description": "Fetches the image data and metadata associated with the specified DID.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the image to retrieve." } ], "responses": { "200": { "description": "Successfully retrieved the image data and metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "object", "description": "The image data and metadata.", "properties": { "type": { "type": "string", "description": "The MIME type of the image (e.g., \"image/png\")." }, "width": { "type": "integer", "description": "The width of the image in pixels." }, "height": { "type": "integer", "description": "The height of the image in pixels." }, "bytes": { "type": "integer", "description": "The size of the image in bytes." }, "cid": { "type": "string", "description": "The Content Identifier (CID) of the image." } } } } } } } }, "404": { "description": "Image not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating the image was not found." } } } } } } } } }, "/images/{id}/test": { "post": { "summary": "Test if the specified image is valid.", "description": "Checks whether the image associated with the given DID is valid or meets specific criteria.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the image to test." } ], "responses": { "200": { "description": "The result of the test.", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean", "description": "true if the image is valid, otherwise `false`." } } } } } }, "400": { "description": "Invalid request or test criteria not met.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the test failed." } } } } } } } } }, "/documents": { "post": { "summary": "Upload a binary document and create a DID for it.", "description": "Accepts binary data as the request body and creates a DID for the uploaded document. Additional options can be passed via the `X-Options` header.\n", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "description": "The binary document data to store as a DID asset." }, "parameters": [ { "in": "header", "name": "X-Options", "required": false, "schema": { "type": "string" }, "description": "A JSON string containing additional options for the document creation process. Example: `{\"registry\":\"local\",\"validUntil\":\"2025-12-31T23:59:59Z\"}`\n" } ], "responses": { "200": { "description": "The DID created for the uploaded document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID representing the uploaded document." } } } } } }, "500": { "description": "Internal server error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/documents/{id}": { "put": { "summary": "Update an existing binary document.", "description": "Updates the binary data of an existing document identified by its DID. Additional options can be passed via the `X-Options` header.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the document to update." }, { "in": "header", "name": "X-Options", "required": false, "schema": { "type": "string" }, "description": "A JSON string containing additional options for the document update process. Example: `{\"registry\":\"local\",\"validUntil\":\"2025-12-31T23:59:59Z\"}`\n" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "description": "The new binary document data to replace the existing one." }, "responses": { "200": { "description": "Indicates whether the update was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the update was successful, otherwise `false`." } } } } } }, "500": { "description": "Internal server error.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "get": { "summary": "Retrieve a binary document by its DID.", "description": "Fetches the binary document data and metadata associated with the specified DID.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the document to retrieve." } ], "responses": { "200": { "description": "Successfully retrieved the document data and metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "object", "description": "The document data and metadata.", "properties": { "type": { "type": "string", "description": "The MIME type of the document (e.g., \"application/pdf\")." }, "bytes": { "type": "integer", "description": "The size of the document in bytes." }, "cid": { "type": "string", "description": "The Content Identifier (CID) of the document." } } } } } } } }, "404": { "description": "Document not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating the document was not found." } } } } } } } } }, "/documents/{id}/test": { "post": { "summary": "Test if the specified document is valid.", "description": "Checks whether the document associated with the given DID is valid or meets specific criteria.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the document to test." } ], "responses": { "200": { "description": "The result of the test.", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean", "description": "true if the document is valid, otherwise `false`." } } } } } }, "400": { "description": "Invalid request or test criteria not met.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the test failed." } } } } } } } } }, "/cas/data/{cid}": { "get": { "summary": "Retrieve data from the CAS (Content Addressable Storage)", "parameters": [ { "in": "path", "name": "cid", "required": true, "schema": { "type": "string" }, "description": "The CID (Content Identifier) of the data to retrieve" } ], "responses": { "200": { "description": "Successfully retrieved the data", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Data not found", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/groupVaults": { "post": { "summary": "Create a new group vault.", "description": "Creates a new group vault asset and returns its DID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": "object", "description": "Additional options for group vault creation.", "properties": { "registry": { "type": "string", "description": "The registry in which to create the group vault DID (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Optional expiration date/time for the group vault." } } } } } } } }, "responses": { "200": { "description": "The DID of the newly created group vault.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID representing the group vault." } } } } } }, "500": { "description": "Internal server error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/groupVaults/{id}": { "get": { "summary": "Retrieve a group vault by DID.", "description": "Returns the group vault object for the specified DID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the group vault to retrieve." } ], "responses": { "200": { "description": "The group vault object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "groupVault": { "type": "object", "properties": { "publicJwk": { "type": "object", "description": "The public JWK for the group vault." }, "salt": { "type": "string", "description": "The salt used for key derivation." }, "keys": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Encrypted keys for each member." }, "items": { "type": "string", "description": "Encrypted items index." } } } } } } } }, "404": { "description": "Group vault not found.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/groupVaults/{id}/test": { "post": { "summary": "Test if a DID refers to a valid group vault.", "description": "Checks whether the specified DID or name refers to a valid group vault asset.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the group vault to test." } ], "responses": { "200": { "description": "Indicates whether the asset is recognized as a valid group vault.", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean", "description": "true if valid group vault, otherwise false." } } } } } }, "404": { "description": "Group vault not found or invalid.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/groupVaults/{id}/members": { "post": { "summary": "Add a member to a group vault.", "description": "Adds a new member to the specified group vault if the caller has permission.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the group vault." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memberId": { "type": "string", "description": "The DID of the member to add to the group vault." } }, "required": [ "memberId" ] } } } }, "responses": { "200": { "description": "Indicates whether the member was successfully added.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the member was added, otherwise false." } } } } } }, "404": { "description": "Group vault not found, member not found, or caller is not authorized.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "get": { "summary": "List all members of a group vault. (available only to group vault owner)", "description": "Returns an object containing all member DIDs of the specified group vault.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the group vault." } ], "responses": { "200": { "description": "An object containing all member DIDs and their metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "object", "additionalProperties": { "type": "object", "description": "Metadata for each member (e.g., join date)." } } } } } } }, "404": { "description": "Group vault not found or caller is not authorized.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/groupVaults/{id}/members/{member}": { "delete": { "summary": "Remove a member from a group vault.", "description": "Removes the specified member from the group vault if the caller has permission.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the group vault." }, { "in": "path", "name": "member", "required": true, "schema": { "type": "string" }, "description": "The DID of the member to remove from the group vault." } ], "responses": { "200": { "description": "Indicates whether the member was successfully removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the member was removed, otherwise false." } } } } } }, "404": { "description": "Member not found, group vault not found, or caller is not authorized.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/groupVaults/{id}/items": { "post": { "summary": "Add an item to a group vault.", "description": "Adds a new item (binary data) to the specified group vault. The item name must be provided in the X-Options header as JSON.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the group vault." }, { "in": "header", "name": "X-Options", "required": true, "schema": { "type": "string" }, "description": "A JSON string containing additional options, including the item name. Example: {\"name\":\"myfile.txt\"}\n" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "The binary data to store as an item in the group vault." } } } }, "responses": { "200": { "description": "Indicates whether the item was successfully added.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the item was added, otherwise false." } } } } } }, "500": { "description": "Internal server error.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "get": { "summary": "List all items in a group vault.", "description": "Returns an index of all items stored in the specified group vault.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the group vault." } ], "responses": { "200": { "description": "An object mapping item names to their metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "object", "additionalProperties": { "type": "object", "description": "Metadata for each item (such as CID and byte size)." } } } } } } }, "404": { "description": "Group vault not found or caller is not a member.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/groupVaults/{id}/items/{name}": { "delete": { "summary": "Remove an item from a group vault.", "description": "Deletes the specified item from the group vault if the caller has permission.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the group vault." }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name of the item to remove from the group vault." } ], "responses": { "200": { "description": "Indicates whether the item was successfully removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the item was removed, otherwise false." } } } } } }, "404": { "description": "Item not found, group vault not found, or caller is not a member.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "get": { "summary": "Retrieve an item from a group vault.", "description": "Returns the binary data for a specific item stored in the group vault.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the group vault." }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name of the item to retrieve from the group vault." } ], "responses": { "200": { "description": "The binary data of the requested item.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Item not found or caller is not a member of the group vault.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/dmail": { "get": { "summary": "List all Dmail messages for the current wallet identity.", "description": "Returns a mapping of Dmail DIDs to Dmail item objects for the current wallet identity.", "responses": { "200": { "description": "A mapping of Dmail DIDs to Dmail item objects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dmail": { "type": "object", "additionalProperties": { "type": "object" }, "description": "An object where each key is a Dmail DID, and each value is the associated Dmail item." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Create a new Dmail message.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "The Dmail message object to create.", "example": { "to": [ "did:mdip:abc123", "did:mdip:def456" ], "cc": [ "did:mdip:ghi789" ], "subject": "Hello World", "body": "This is a test Dmail message." } }, "options": { "type": "object", "description": "Additional creation options (e.g., registry, validUntil)." } } } } } }, "responses": { "200": { "description": "The DID of the newly created Dmail message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID representing the new Dmail message." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/dmail/import": { "post": { "summary": "Import a Dmail message into the inbox.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID of the Dmail message to import." } } } } } }, "responses": { "200": { "description": "Indicates whether the import was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/dmail/{id}": { "get": { "summary": "Retrieve a Dmail message by DID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the Dmail message to retrieve." } ], "responses": { "200": { "description": "The Dmail message object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "The Dmail message." } } } } } }, "404": { "description": "Dmail not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "put": { "summary": "Update an existing Dmail message.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the Dmail message to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "The updated Dmail message object." } } } } } }, "responses": { "200": { "description": "Indicates whether the update was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Remove a Dmail message from the mailbox.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the Dmail message to remove." } ], "responses": { "200": { "description": "Indicates whether the removal was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/dmail/{id}/send": { "post": { "summary": "Create a Notice and mark a Dmail message as sent.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the Dmail message to send." } ], "responses": { "200": { "description": "The DID of the notice created for the sent Dmail message.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID of the notice created for this sent Dmail." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/dmail/{id}/file": { "post": { "summary": "File (move) a Dmail message to a different folder by updating its tags.", "description": "Updates the tags of a Dmail message, allowing it to be moved between folders such as inbox, archive, or trash.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the Dmail message to file." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "The new tags to assign to the Dmail message (e.g., [\"inbox\"], [\"archived\"], [\"deleted\"])." } }, "required": [ "tags" ] } } } }, "responses": { "200": { "description": "Indicates whether the filing operation was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/dmail/{id}/attachments": { "get": { "summary": "List all attachments for a specific Dmail message.", "description": "Returns a mapping of attachment names to their metadata for the specified Dmail DID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the Dmail message whose attachments should be listed." } ], "responses": { "200": { "description": "A mapping of attachment names to their metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachments": { "type": "object", "additionalProperties": { "type": "object" }, "description": "An object where each key is an attachment name, and each value is the associated metadata." } } } } } }, "404": { "description": "Dmail message or attachments not found.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "post": { "summary": "Add an attachment to a specific Dmail message.", "description": "Uploads a binary attachment and associates it with the specified Dmail message. The attachment name must be provided in the X-Options header as JSON.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the Dmail message to attach the file to." }, { "in": "header", "name": "X-Options", "required": true, "schema": { "type": "string" }, "description": "A JSON string containing additional options, including the attachment name. Example: {\"name\":\"myfile.txt\"}\n" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "The binary data of the attachment to upload." } } } }, "responses": { "200": { "description": "Indicates whether the attachment was successfully added.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the attachment was added, otherwise false." } } } } } }, "500": { "description": "Internal server error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/dmail/{id}/attachments/{name}": { "delete": { "summary": "Remove an attachment from a specific Dmail message.", "description": "Deletes the specified attachment from the Dmail message identified by its DID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the Dmail message." }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name of the attachment to remove." } ], "responses": { "200": { "description": "Indicates whether the attachment was successfully removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the attachment was removed, otherwise false." } } } } } }, "404": { "description": "Dmail message or attachment not found.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "get": { "summary": "Download a specific attachment from a Dmail message.", "description": "Returns the binary data for the specified attachment associated with the given Dmail DID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the Dmail message." }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name of the attachment to download." } ], "responses": { "200": { "description": "The binary data of the requested attachment.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Attachment or Dmail message not found.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/notices": { "post": { "summary": "Create a new notice asset.", "description": "Creates a new notice asset (e.g., for Dmail delivery) and returns its DID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "The NoticeMessage object to create.", "example": { "to": [ "did:mdip:abc123", "did:mdip:def456" ], "dids": [ "did:mdip:dmail1", "did:mdip:dmail2" ] } }, "options": { "type": "object", "description": "Additional creation options (e.g., registry, validUntil)." } } } } } }, "responses": { "200": { "description": "The DID of the newly created notice.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID representing the new notice." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/notices/{id}": { "put": { "summary": "Update an existing notice asset.", "description": "Updates the NoticeMessage data for the specified notice DID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the notice to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "description": "The updated NoticeMessage object.", "example": { "to": [ "did:mdip:abc123", "did:mdip:def456" ], "dids": [ "did:mdip:dmail1", "did:mdip:dmail2" ] } } } } } } }, "responses": { "200": { "description": "Indicates whether the update was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/notices/refresh": { "post": { "summary": "Refresh all notices.", "description": "Refreshes the state of all notice assets, updating any that have changed.", "responses": { "200": { "description": "Indicates whether the refresh operation was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the refresh was successful, otherwise false." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } } }, "tags": [] }