{ "openapi": "3.0.0", "info": { "title": "Keymaster API", "version": "0.5.0", "description": "Documentation for Keymaster API" }, "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" } } } } } } } } }, "/api/v1/version": { "get": { "summary": "Retrieve the API version", "responses": { "200": { "description": "The API version and commit hash.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "commit": { "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": { "type": "object", "properties": { "seed": { "type": "object", "properties": { "mnemonic": { "type": "string" }, "hdkey": { "type": "object", "properties": { "xpriv": { "type": "string" }, "xpub": { "type": "string" } } } } }, "counter": { "type": "integer" }, "ids": { "type": "object", "additionalProperties": { "type": "object", "properties": { "did": { "type": "string" }, "account": { "type": "integer" }, "index": { "type": "integer" }, "owned": { "type": "array", "items": { "type": "string" } } } } }, "current": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } }, "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": { "type": "object", "properties": { "seed": { "type": "object", "properties": { "mnemonic": { "type": "string" }, "hdkey": { "type": "object", "properties": { "xpriv": { "type": "string" }, "xpub": { "type": "string" } } } } }, "counter": { "type": "integer" }, "ids": { "type": "object", "additionalProperties": { "type": "object", "properties": { "did": { "type": "string" }, "account": { "type": "integer" }, "index": { "type": "integer" }, "owned": { "type": "array", "items": { "type": "string" } } } } }, "current": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "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": false, "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": { "type": "object", "properties": { "seed": { "type": "object", "properties": { "mnemonic": { "type": "string" }, "hdkey": { "type": "object", "properties": { "xpriv": { "type": "string" }, "xpub": { "type": "string" } } } } }, "counter": { "type": "integer" }, "ids": { "type": "object", "additionalProperties": { "type": "object", "properties": { "did": { "type": "string" }, "account": { "type": "integer" }, "index": { "type": "integer" }, "owned": { "type": "array", "items": { "type": "string" } } } } }, "current": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } }, "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": { "type": "object", "properties": { "seed": { "type": "object", "properties": { "mnemonic": { "type": "string" }, "hdkey": { "type": "object", "properties": { "xpriv": { "type": "string" }, "xpub": { "type": "string" } } } } }, "counter": { "type": "integer" }, "ids": { "type": "object", "additionalProperties": { "type": "object", "properties": { "did": { "type": "string" }, "account": { "type": "integer" }, "index": { "type": "integer" }, "owned": { "type": "array", "items": { "type": "string" } } } } }, "current": { "type": "string" }, "names": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } }, "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" }, "aliasesRemoved": { "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" } } } } } } } } }, "/wallet/passphrase": { "post": { "summary": "Change the wallet passphrase.", "description": "Re-encrypts the wallet mnemonic with a new passphrase. All DIDs and derived identities are preserved.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passphrase": { "type": "string", "description": "The new passphrase." } }, "required": [ "passphrase" ] } } } }, "responses": { "200": { "description": "Passphrase changed 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" } } } } } } } } }, "/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": { "type": "object", "properties": { "version": { "type": "integer", "description": "The wallet format version." }, "seed": { "type": "object", "properties": { "mnemonicEnc": { "type": "object", "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." } } } } }, "enc": { "type": "string", "description": "Encrypted wallet data (IDs, names, etc.)." } } } } } } } }, "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, returns the DID Document only if it is fully confirmed on the registry it references.\n" }, { "in": "query", "name": "verify", "required": false, "schema": { "type": "boolean" }, "description": "If true, verifies the proof(s) of the DID operation(s) before returning the DID Document. If a proof 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": { "@context": { "type": "string", "description": "DID resolution context (usually \"https://w3id.org/did-resolution/v1\")." }, "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": "integer" }, "versionId": { "type": "string", "description": "A CID or similar identifier for the version." }, "canonicalId": { "type": "string" }, "confirmed": { "type": "boolean" }, "deactivated": { "type": "boolean" } } }, "didDocumentData": { "type": "object", "description": "Arbitrary data attached to the DID (only present for assets)." }, "didDocumentRegistration": { "type": "object", "description": "Registration metadata fields.", "properties": { "type": { "type": "string", "enum": [ "agent", "asset" ] }, "registry": { "type": "string", "enum": [ "local", "hyperswarm", "BTC:mainnet", "BTC:testnet4", "BTC:signet" ] }, "version": { "type": "integer" }, "validUntil": { "type": "string", "format": "date-time" }, "registration": { "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" } } } } } } } }, "put": { "summary": "Update a DID document.", "description": "Updates the DID document with the provided data.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "doc": { "type": "object", "description": "The DID document fields to update." } } } } } }, "responses": { "200": { "description": "Indicates whether the DID was successfully updated.", "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" } } } } } } } } }, "/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", "BTC:testnet4", "BTC:signet" ] } } } } } } } }, "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}/change-registry": { "post": { "summary": "Change the registry for an existing DID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID name or DID to change the registry for." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "registry": { "type": "string" } }, "required": [ "registry" ] } } } }, "responses": { "200": { "description": "Indicates whether the registry change was successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid registry or other error.", "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" } } } } } } } } }, "/aliases": { "get": { "summary": "List all alias-to-DID mappings in the wallet.", "responses": { "200": { "description": "A list of all alias-to-DID mappings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "aliases": { "type": "object", "additionalProperties": { "type": "string" }, "description": "An object where each key is an alias, 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 alias-to-DID mapping.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alias": { "type": "string", "description": "The human-readable alias to associate with the DID." }, "did": { "type": "string", "description": "The DID that this alias should refer to." } }, "required": [ "alias", "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" } } } } } } } } }, "/aliases/{alias}": { "get": { "summary": "Retrieve the DID associated with a specific alias.", "description": "Returns the DID for the provided human-readable alias, if it exists.", "parameters": [ { "in": "path", "name": "alias", "required": true, "schema": { "type": "string" }, "description": "The alias for which you want the associated DID." } ], "responses": { "200": { "description": "The DID associated with the requested alias.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "404": { "description": "The requested alias was not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Remove an existing alias-to-DID mapping.", "parameters": [ { "in": "path", "name": "alias", "required": true, "schema": { "type": "string" }, "description": "The alias 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 alias was invalid or could not be removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/nostr": { "post": { "summary": "Add Nostr keys to the current identity.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identity name (optional, defaults to current)." } } } } } }, "responses": { "200": { "description": "The generated Nostr keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "npub": { "type": "string" }, "pubkey": { "type": "string" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "Remove Nostr keys from the current identity.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identity name (optional, defaults to current)." } } } } } }, "responses": { "200": { "description": "Whether the removal succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/nostr/nsec": { "post": { "summary": "Export the Nostr private key (nsec) for the current identity.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identity name (optional, defaults to current)." } } } } } }, "responses": { "200": { "description": "The bech32-encoded nsec private key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "nsec": { "type": "string" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/nostr/sign": { "post": { "summary": "Sign a Nostr event with the current identity's key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "created_at": { "type": "integer" }, "kind": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "content": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "The signed Nostr event with id, pubkey, and sig fields.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "pubkey": { "type": "string" }, "created_at": { "type": "integer" }, "kind": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "content": { "type": "string" }, "sig": { "type": "string" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/lightning": { "post": { "summary": "Create a Lightning wallet for the current identity.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional identity name or DID." } } } } } }, "responses": { "200": { "description": "Lightning wallet configuration." }, "400": { "description": "Error creating Lightning wallet." } } }, "delete": { "summary": "Remove Lightning wallet from the current identity.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional identity name or DID." } } } } } }, "responses": { "200": { "description": "Success." }, "400": { "description": "Error removing Lightning wallet." } } } }, "/lightning/balance": { "post": { "summary": "Get Lightning wallet balance for the current identity.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional identity name or DID." } } } } } }, "responses": { "200": { "description": "Balance in sats." }, "400": { "description": "Error getting balance." } } } }, "/lightning/invoice": { "post": { "summary": "Create a Lightning invoice to receive sats.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "memo" ], "properties": { "amount": { "type": "number", "description": "Amount in sats." }, "memo": { "type": "string", "description": "Invoice description." }, "id": { "type": "string", "description": "Optional identity name or DID." } } } } } }, "responses": { "200": { "description": "Lightning invoice." }, "400": { "description": "Error creating invoice." } } } }, "/lightning/pay": { "post": { "summary": "Pay a Lightning invoice.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bolt11" ], "properties": { "bolt11": { "type": "string", "description": "BOLT11 invoice string." }, "id": { "type": "string", "description": "Optional identity name or DID." } } } } } }, "responses": { "200": { "description": "Payment result." }, "400": { "description": "Error paying invoice." } } } }, "/lightning/payment": { "post": { "summary": "Check status of a Lightning payment.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "paymentHash" ], "properties": { "paymentHash": { "type": "string", "description": "Payment hash to check." }, "id": { "type": "string", "description": "Optional identity name or DID." } } } } } }, "responses": { "200": { "description": "Payment status." }, "400": { "description": "Error checking payment." } } } }, "/lightning/decode": { "post": { "summary": "Decode a Lightning BOLT11 invoice.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bolt11": { "type": "string" } } } } } }, "responses": { "200": { "description": "Decoded invoice details." }, "400": { "description": "Error decoding invoice." } } } }, "/lightning/publish": { "post": { "summary": "Publish Lightning service endpoint for a DID.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Lightning published successfully." }, "400": { "description": "Error publishing Lightning." } } } }, "/lightning/unpublish": { "post": { "summary": "Unpublish Lightning service endpoint for a DID.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Lightning unpublished successfully." }, "400": { "description": "Error unpublishing Lightning." } } } }, "/lightning/zap": { "post": { "summary": "Send sats to a DID via Lightning.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" }, "amount": { "type": "integer" }, "memo": { "type": "string" }, "id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Payment result with preimage." }, "400": { "description": "Error sending payment." } } } }, "/lightning/payments": { "post": { "summary": "Get Lightning payment history.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } } } } } }, "responses": { "200": { "description": "List of payments." }, "400": { "description": "Error fetching payments." } } } }, "/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", "BTC:testnet4", "BTC:signet" ] }, "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 }, "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 proof(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" } } } } } } } } }, "/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": { "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": { "schema": { "type": "string", "description": "The schema DID or name to which this credential conforms." }, "claims": { "type": "object", "description": "Claims to include in the credential. If omitted, defaults are generated from the schema." }, "types": { "type": "array", "items": { "type": "string" }, "description": "Additional semantic types to add to the credential type array." }, "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." } ], "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 proof 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 `proof` 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 proof.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "json": { "type": "object", "description": "The JSON object to verify, which must include a `proof` property." } }, "required": [ "json" ] } } } }, "responses": { "200": { "description": "Whether the proof is valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "true if the proof 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." } } } } } }, "404": { "description": "Schema not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating the schema was not found." } } } } } }, "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." }, "alias": { "type": "string", "description": "A human-readable alias 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": { "version": { "type": "integer" }, "name": { "type": "string" }, "description": { "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 (backed by a vault).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "poll": { "type": "object", "description": "The poll configuration.", "properties": { "version": { "type": "integer", "default": 2, "description": "Must be 2." }, "name": { "type": "string", "description": "A short name for the poll (used as alias when imported)." }, "description": { "type": "string", "description": "A short description or question for the poll." }, "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": [ "version", "name", "description", "options", "deadline" ] }, "options": { "type": "object", "description": "Vault creation options.", "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." }, "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/ballot/send": { "post": { "summary": "Send a ballot to the poll owner via notice.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ballot": { "type": "string", "description": "The DID of the ballot to send." }, "poll": { "type": "string", "description": "The DID of the poll." } }, "required": [ "ballot", "poll" ] } } } }, "responses": { "200": { "description": "The DID of the notice sent to the poll owner.", "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/ballot/{did}": { "get": { "summary": "View ballot details.", "description": "Returns ballot details. The poll owner can see the vote; others see only metadata.", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The DID of the ballot." } ], "responses": { "200": { "description": "Ballot details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ballot": { "type": "object", "properties": { "poll": { "type": "string" }, "voter": { "type": "string" }, "vote": { "type": "integer" }, "option": { "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 config (type, version, description, options, deadline)." } } } } } }, "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}/send": { "post": { "summary": "Send a poll notice to all voters.", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string" } } } } } }, "500": { "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 ballot is encrypted for the poll owner only.\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 to cast a spoiled ballot." }, "options": { "type": "object", "description": "Additional vote parameters.", "properties": { "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." } } } }, "required": [ "vote" ] } } } }, "responses": { "200": { "description": "The DID representing the newly created ballot (to be sent 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 vault.", "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 vault.", "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" } } } } } } } } }, "/polls/{poll}/voters": { "post": { "summary": "Add a voter to a poll.", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the poll." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memberId": { "type": "string", "description": "The DID of the voter to add." } }, "required": [ "memberId" ] } } } }, "responses": { "200": { "description": "Indicates whether the voter 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" } } } } } } } }, "get": { "summary": "List all voters of a poll.", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the poll." } ], "responses": { "200": { "description": "An object containing all voter DIDs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "voters": { "type": "object" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/polls/{poll}/voters/{voter}": { "delete": { "summary": "Remove a voter from a poll.", "parameters": [ { "in": "path", "name": "poll", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the poll." }, { "in": "path", "name": "voter", "required": true, "schema": { "type": "string" }, "description": "The DID of the voter to remove." } ], "responses": { "200": { "description": "Indicates whether the voter 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" } } } } } } } } }, "/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": { "application/json": { "schema": { "type": "object", "properties": { "error": { "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." }, { "in": "header", "name": "X-Options", "required": false, "schema": { "type": "string" }, "description": "A JSON string containing additional options (e.g., filename).\n" } ], "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": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "get": { "summary": "Retrieve an image by its DID.", "description": "Fetches the image file 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": { "file": { "type": "object", "description": "The file data and metadata.", "properties": { "cid": { "type": "string", "description": "The Content Identifier (CID) of the image." }, "filename": { "type": "string", "description": "The filename of the image." }, "type": { "type": "string", "description": "The MIME type of the image (e.g., \"image/png\")." }, "bytes": { "type": "integer", "description": "The size of the image in bytes." } } }, "image": { "type": "object", "description": "The image-specific metadata.", "properties": { "width": { "type": "integer", "description": "The width of the image in pixels." }, "height": { "type": "integer", "description": "The height of the image in pixels." } } } } } } } }, "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." } } } } } } } } }, "/files": { "post": { "summary": "Upload a binary file and create a DID for it.", "description": "Accepts binary data as the request body and creates a DID for the uploaded file. 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 file 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 file creation process. Example: `{\"registry\":\"local\",\"validUntil\":\"2025-12-31T23:59:59Z\"}`\n" } ], "responses": { "200": { "description": "The DID created for the uploaded file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID representing the uploaded file." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/files/{id}": { "put": { "summary": "Update an existing binary file.", "description": "Updates the binary data of an existing file 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 file to update." }, { "in": "header", "name": "X-Options", "required": false, "schema": { "type": "string" }, "description": "A JSON string containing additional options for the file 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 file 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": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "get": { "summary": "Retrieve a binary file by its DID.", "description": "Fetches the binary file data and metadata associated with the specified DID.\n", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the file to retrieve." } ], "responses": { "200": { "description": "Successfully retrieved the file data and metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "description": "The file data and metadata.", "properties": { "type": { "type": "string", "description": "The MIME type of the file (e.g., \"application/pdf\")." }, "bytes": { "type": "integer", "description": "The size of the file in bytes." }, "cid": { "type": "string", "description": "The Content Identifier (CID) of the file." } } } } } } } }, "404": { "description": "File not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating the file was not found." } } } } } } } } }, "/files/{id}/test": { "post": { "summary": "Test if the specified file is valid.", "description": "Checks whether the file 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 file to test." } ], "responses": { "200": { "description": "The result of the test.", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean", "description": "true if the file 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." } } } } } } } } }, "/ipfs/data/{cid}": { "get": { "summary": "Retrieve data from the IPFS", "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": { "application/json": { "schema": { "type": "string", "example": "Not Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/vaults": { "post": { "summary": "Create a new vault.", "description": "Creates a new vault asset and returns its DID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": "object", "description": "Additional options for vault creation.", "properties": { "registry": { "type": "string", "description": "The registry in which to create the vault DID (e.g., \"local\", \"hyperswarm\")." }, "validUntil": { "type": "string", "format": "date-time", "description": "Optional expiration date/time for the vault." } } } } } } } }, "responses": { "200": { "description": "The DID of the newly created vault.", "content": { "application/json": { "schema": { "type": "object", "properties": { "did": { "type": "string", "description": "The DID representing the vault." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/vaults/{id}": { "get": { "summary": "Retrieve a vault by DID.", "description": "Returns the vault object for the specified DID.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the vault to retrieve." } ], "responses": { "200": { "description": "The vault object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "vault": { "type": "object", "properties": { "publicJwk": { "type": "object", "description": "The public JWK for the 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": "Vault not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the vault could not be retrieved." } } } } } } } } }, "/vaults/{id}/test": { "post": { "summary": "Test if a DID refers to a valid vault.", "description": "Checks whether the specified DID or name refers to a valid vault asset.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID or name of the vault to test." } ], "responses": { "200": { "description": "Indicates whether the asset is recognized as a valid vault.", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean", "description": "true if valid vault, otherwise false." } } } } } }, "404": { "description": "Vault not found or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the vault could not be tested." } } } } } } } } }, "/vaults/{id}/members": { "post": { "summary": "Add a member to a vault.", "description": "Adds a new member to the specified vault if the caller has permission.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the vault." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memberId": { "type": "string", "description": "The DID of the member to add to the 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": "Vault not found, member not found, or caller is not authorized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the member could not be added." } } } } } } } }, "get": { "summary": "List all members of a vault. (available only to vault owner)", "description": "Returns an object containing all member DIDs of the specified vault.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the 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": "Vault not found or caller is not authorized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the members could not be listed." } } } } } } } } }, "/vaults/{id}/members/{member}": { "delete": { "summary": "Remove a member from a vault.", "description": "Removes the specified member from the vault if the caller has permission.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the vault." }, { "in": "path", "name": "member", "required": true, "schema": { "type": "string" }, "description": "The DID of the member to remove from the 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, vault not found, or caller is not authorized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the member could not be removed." } } } } } } } } }, "/vaults/{id}/items": { "post": { "summary": "Add an item to a vault.", "description": "Adds a new item (binary data) to the specified 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 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 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": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "get": { "summary": "List all items in a vault.", "description": "Returns an index of all items stored in the specified vault.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the 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": "Vault not found or caller is not a member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the items could not be listed." } } } } } } } } }, "/vaults/{id}/items/{name}": { "delete": { "summary": "Remove an item from a vault.", "description": "Deletes the specified item from the vault if the caller has permission.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the vault." }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name of the item to remove from the 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, vault not found, or caller is not a member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the item could not be removed." } } } } } } } }, "get": { "summary": "Retrieve an item from a vault.", "description": "Returns the binary data for a specific item stored in the vault.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The DID of the vault." }, { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "The name of the item to retrieve from the 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 vault.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating why the item could not be retrieved." } } } } } } } } }, "/dmail": { "get": { "summary": "List all Dmail messages for the current or specified owner.", "description": "Returns a mapping of Dmail DIDs to Dmail item objects for the current wallet or for the specified owner.", "parameters": [ { "in": "query", "name": "owner", "required": false, "schema": { "type": "string" }, "description": "The name or DID of the owner whose Dmail messages should be listed." } ], "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": "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:cid:abc123", "did:cid:def456" ], "cc": [ "did:cid: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": { "application/json": { "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": { "application/json": { "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": { "application/json": { "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": { "application/json": { "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:cid:abc123", "did:cid:def456" ], "dids": [ "did:cid:dmail1", "did:cid: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:cid:abc123", "did:cid:def456" ], "dids": [ "did:cid:dmail1", "did:cid: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" } } } } } } } } } }, "components": {}, "tags": [] }