{ "openapi": "3.0.0", "info": { "title": "Gatekeeper API", "version": "2.1.0", "description": "Documentation for Gatekeeper API" }, "servers": [ { "url": "http://localhost:4224/api/v1", "description": "Local Gatekeeper" } ], "paths": { "/ready": { "get": { "summary": "Check if the Gatekeeper service is ready.", "responses": { "200": { "description": "Gatekeeper service is ready.", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "500": { "description": "The readiness check failed.", "content": { "text/html": { "schema": { "type": "string" } } } }, "503": { "description": "Gatekeeper service is not ready.", "content": { "application/json": { "schema": { "type": "boolean", "example": false } } } } } } }, "/version": { "get": { "summary": "Retrieve the API version", "responses": { "200": { "description": "The API version number.", "content": { "application/json": { "schema": { "type": "integer" } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/status": { "get": { "summary": "Retrieve server status", "responses": { "200": { "description": "Status information retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uptimeSeconds": { "type": "integer", "description": "The number of seconds since the server started." }, "dids": { "type": "object", "description": "Detailed statistics of DID checks.", "properties": { "total": { "type": "integer", "description": "Total number of DIDs processed." }, "byType": { "type": "object", "description": "Breakdown of DIDs by type.", "properties": { "agents": { "type": "integer", "description": "Number of DIDs of type \"agent\"." }, "assets": { "type": "integer", "description": "Number of DIDs of type \"asset\"." }, "confirmed": { "type": "integer", "description": "Number of DIDs that have been confirmed." }, "unconfirmed": { "type": "integer", "description": "Number of DIDs that remain unconfirmed." }, "ephemeral": { "type": "integer", "description": "Number of DIDs with an expiration (validUntil) set." }, "invalid": { "type": "integer", "description": "Number of DIDs that could not be resolved or are invalid." } } }, "byRegistry": { "type": "object", "description": "Count of DIDs grouped by registry.", "additionalProperties": { "type": "integer" } }, "byVersion": { "type": "object", "description": "Count of DIDs grouped by version.", "additionalProperties": { "type": "integer" } }, "eventsQueue": { "type": "object", "description": "Details of the events queue." } } }, "memoryUsage": { "type": "object", "description": "Memory usage statistics provided by Node.", "properties": { "rss": { "type": "integer", "description": "Resident Set Size – total memory allocated for the process." }, "heapTotal": { "type": "integer", "description": "Total size of the allocated heap." }, "heapUsed": { "type": "integer", "description": "Actual memory used during execution." }, "external": { "type": "integer", "description": "Memory usage of C++ objects bound to JavaScript objects managed by V8." }, "arrayBuffers": { "type": "integer", "description": "Memory allocated for ArrayBuffers and SharedArrayBuffers." } } } } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/did": { "post": { "summary": "Create, update, or delete a DID", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "created", "mdip", "signature" ], "properties": { "type": { "type": "string", "enum": [ "create" ], "description": "Must be \"create\" to create a new DID." }, "created": { "type": "string", "format": "date-time", "description": "Timestamp of when the operation was created." }, "mdip": { "type": "object", "required": [ "version", "type", "registry" ], "properties": { "version": { "type": "integer", "description": "MDIP version (e.g., 1)." }, "type": { "type": "string", "enum": [ "agent", "asset" ], "description": "MDIP type." }, "registry": { "type": "string", "description": "Registry where the DID is created." }, "prefix": { "type": "string", "description": "Optional DID prefix override. If omitted, the server default is used." }, "validUntil": { "type": "string", "format": "date-time", "description": "Optional expiration time for ephemeral DIDs." } }, "description": "MDIP metadata fields for creation." }, "signature": { "type": "object", "description": "Cryptographic signature verifying the create operation.", "required": [ "value", "signed", "hash" ], "properties": { "value": { "type": "string", "description": "The signature value (base64, hex, etc.)." }, "signed": { "type": "string", "format": "date-time", "description": "When the signature was created." }, "signer": { "type": "string", "description": "The DID of the signer (for asset creation, should match `controller`)." }, "hash": { "type": "string", "description": "SHA-256 hash of the operation payload." } } }, "publicJwk": { "type": "object", "description": "Required if mdip.type = \"agent\". Contains the public key in JWK format." }, "controller": { "type": "string", "description": "Required if mdip.type = \"asset\". Must match the `signer` in `signature`." }, "data": { "description": "Optional arbitrary JSON data for an asset DID." }, "blockid": { "type": "string", "description": "Optional current block hash or identifier used when creating the DID." } } }, { "type": "object", "required": [ "type", "did", "previd", "signature" ], "properties": { "type": { "type": "string", "enum": [ "update" ], "description": "Must be \"update\" to modify an existing DID document." }, "did": { "type": "string", "description": "The DID to update." }, "doc": { "type": "object", "description": "The complete DID document that replaces the current document." }, "previd": { "type": "string", "description": "Reference to the previous version CID/hash." }, "blockid": { "type": "string", "description": "Optional current block hash or identifier." }, "signature": { "type": "object", "required": [ "value", "signed", "hash" ], "description": "Cryptographic signature verifying this update operation.", "properties": { "value": { "type": "string", "description": "The signature value (base64, hex, etc.)." }, "signed": { "type": "string", "format": "date-time", "description": "When the signature was created." }, "signer": { "type": "string", "description": "The DID of the signer (often the same as `did`)." }, "hash": { "type": "string", "description": "SHA-256 hash of the operation payload." } } } } }, { "type": "object", "required": [ "type", "did", "previd", "signature" ], "properties": { "type": { "type": "string", "enum": [ "delete" ], "description": "Must be \"delete\" to deactivate an existing DID." }, "did": { "type": "string", "description": "The DID to deactivate." }, "previd": { "type": "string", "description": "Reference to the previous version CID/hash." }, "blockid": { "type": "string", "description": "Optional current block hash or identifier." }, "signature": { "type": "object", "required": [ "value", "signed", "hash" ], "description": "Cryptographic signature verifying this delete operation.", "properties": { "value": { "type": "string", "description": "The signature value (base64, hex, etc.)." }, "signed": { "type": "string", "format": "date-time", "description": "When the signature was created." }, "signer": { "type": "string", "description": "The DID of the signer, who must have authority to delete." }, "hash": { "type": "string", "description": "SHA-256 hash of the operation payload." } } } } } ] } } } }, "responses": { "200": { "description": "- If `type = \"create\"`, returns the newly created DID as a string. - Otherwise (for update or delete), returns a boolean value indicating success.\n", "content": { "application/json": { "schema": { "oneOf": [ { "type": "string", "description": "A DID string (when a create operation succeeds).", "example": "did:mdip:z3v8AuahvBGDMXvCTWedYbxnH6C9ZrsEtEJAvip2XPzcZb8yo6A" }, { "type": "boolean", "description": "A success indicator for update/delete operations.", "example": true } ] } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/did/generate": { "post": { "summary": "Generate a DID from an operation (no persistence)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "An MDIP Operation object.", "required": [ "type", "mdip" ], "properties": { "type": { "type": "string", "description": "The operation type. Typically \"create\" when generating a DID." }, "created": { "type": "string", "format": "date-time", "description": "Optional creation timestamp (used by create operations elsewhere)." }, "did": { "type": "string", "description": "Optional DID (usually absent for create when generating)." }, "mdip": { "type": "object", "description": "MDIP metadata for the operation.", "required": [ "version", "type", "registry" ], "properties": { "version": { "type": "integer", "example": 1 }, "type": { "type": "string", "enum": [ "agent", "asset" ], "example": "agent" }, "registry": { "type": "string", "description": "Registry name.", "example": "local" }, "prefix": { "type": "string", "description": "Optional DID prefix override. If omitted, server default is used.", "example": "did:test" }, "validUntil": { "type": "string", "format": "date-time", "description": "Optional expiry timestamp for ephemeral DIDs." } } }, "publicJwk": { "type": "object", "description": "Public key JWK (typically required for agent creates)." }, "controller": { "type": "string", "description": "Controller DID (typically required for asset creates)." }, "data": { "type": "object", "description": "Optional arbitrary DID document data (often used for assets)." }, "signature": { "type": "object", "description": "Optional signature object (not required for mere DID generation)." } } } } } }, "responses": { "200": { "description": "The generated DID string.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request (missing or invalid operation).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/did/{did}": { "get": { "summary": "Resolve a DID Document", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The DID 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.\n" }, { "in": "query", "name": "versionSequence", "required": false, "schema": { "type": "integer" }, "description": "Specific version of the DID Document to retrieve. Versioning increments each time an `update` or `delete` operation occurs.\n" }, { "in": "query", "name": "confirm", "required": false, "schema": { "type": "boolean" }, "description": "If `true`, excludes later events until they are confirmed by the DID's native registry.\n" }, { "in": "query", "name": "verify", "required": false, "schema": { "type": "boolean" }, "description": "If `true`, verifies the signature(s) of the DID operation(s) before returning the DID Document. If a signature is invalid, an error is thrown.\n" } ], "responses": { "200": { "description": "The resolution result. Invalid or unknown DIDs are reported in `didResolutionMetadata.error` with a 200 response.\n", "content": { "application/json": { "schema": { "type": "object", "description": "The fully-resolved DID Document along with metadata describing its state.", "properties": { "didDocument": { "type": "object", "description": "The DID Document itself.", "properties": { "@context": { "type": "array", "items": { "type": "string" }, "description": "DID document context." }, "id": { "type": "string", "description": "The DID." }, "controller": { "type": "string", "description": "The controller DID (for assets)." }, "verificationMethod": { "type": "array", "description": "An array of verification methods (keys).", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for the verification method." }, "controller": { "type": "string", "description": "The DID or entity controlling this key." }, "type": { "type": "string", "description": "Type of key." }, "publicKeyJwk": { "type": "object", "description": "Public key data in JWK format." } } } }, "authentication": { "type": "array", "items": { "type": "string" }, "description": "Refers to the verification methods used for authentication." } } }, "didDocumentMetadata": { "type": "object", "description": "Metadata associated with the DID Document.", "properties": { "created": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the DID was created." }, "updated": { "type": "string", "format": "date-time", "description": "Timestamp indicating the last update to the DID, if any." }, "deleted": { "type": "string", "format": "date-time", "description": "Timestamp of when the DID was deleted (if it was deleted)." }, "version": { "type": "string", "description": "Current version number of the DID Document." }, "versionId": { "type": "string", "description": "CID (or similar) identifying the current version’s content." }, "canonicalId": { "type": "string", "description": "The canonical DID if a custom prefix was used." }, "confirmed": { "type": "boolean", "description": "Indicates whether the DID is fully confirmed." }, "deactivated": { "type": "boolean", "description": "Indicates if the DID is deactivated (via a delete operation)." }, "timestamp": { "type": "object", "description": "Optional blockchain timestamp bounds for the current operation." } } }, "didResolutionMetadata": { "type": "object", "description": "Metadata describing the resolution result.", "properties": { "retrieved": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the DID was resolved." }, "error": { "type": "string", "enum": [ "invalidDid", "notFound" ], "description": "Resolution error for an invalid or unknown DID." } } }, "didDocumentData": { "description": "Arbitrary JSON data attached to the DID (for assets)." }, "mdip": { "type": "object", "description": "MDIP-specific metadata fields.", "properties": { "type": { "type": "string", "enum": [ "agent", "asset" ], "description": "The MDIP type." }, "registry": { "type": "string", "enum": [ "local", "hyperswarm", "TESS", "TBTC", "TFTC", "Signet", "Signet-Inscription", "BTC-Inscription" ], "description": "Registry in which this DID is maintained." }, "version": { "type": "integer", "description": "Supported MDIP version." }, "prefix": { "type": "string", "description": "DID prefix embedded in the operation." }, "validUntil": { "type": "string", "format": "date-time", "description": "Optional expiration timestamp for ephemeral DIDs." } } } } } } } }, "404": { "description": "Resolution failed with an exception.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "post": { "summary": "Update an existing DID (deprecated)", "deprecated": true, "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The DID to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "did", "previd", "signature" ], "properties": { "type": { "type": "string", "enum": [ "update" ], "description": "Must be `\"update\"` for this operation." }, "did": { "type": "string", "description": "The DID being updated. Must match the path parameter `{did}`." }, "doc": { "type": "object", "description": "The complete DID Document that replaces the current document." }, "previd": { "type": "string", "description": "Reference to the previous version." }, "signature": { "type": "object", "description": "Cryptographic signature." } } } } } }, "responses": { "200": { "description": "A boolean indicating if the update was accepted.", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "delete": { "summary": "Delete a DID (deprecated)", "deprecated": true, "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "type": "string" }, "description": "The DID to delete." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "did", "previd", "signature" ], "properties": { "type": { "type": "string", "enum": [ "delete" ], "description": "Must be \"delete\" to deactivate the DID." }, "did": { "type": "string", "description": "The DID being deleted." }, "signature": { "type": "object", "description": "Cryptographic signature." }, "previd": { "type": "string", "description": "Reference to the previous version." } } } } } }, "responses": { "200": { "description": "A boolean indicating whether the deletion was accepted and processed.", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/dids/": { "post": { "summary": "Retrieve a list of DIDs or DID Documents.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "dids": { "type": "array", "description": "A list of specific DIDs to check. If omitted, all known DIDs are retrieved.", "items": { "type": "string" } }, "updatedAfter": { "type": "string", "format": "date-time", "description": "Only return DIDs/DID Docs updated *after* this time." }, "updatedBefore": { "type": "string", "format": "date-time", "description": "Only return DIDs/DID Docs updated *before* this time." }, "confirm": { "type": "boolean", "description": "If true, only return DID Docs that are fully confirmed." }, "verify": { "type": "boolean", "description": "If true, verifies signatures during DID resolution. If signature checks fail, an error is thrown." }, "resolve": { "type": "boolean", "description": "If true, return DID Documents instead of just string identifiers." } } } } } }, "responses": { "200": { "description": "An array of DIDs or DID Documents.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "description": "An array of DID strings.", "items": { "type": "string" } }, { "type": "array", "description": "An array of DID Document objects (if `resolve` is true).", "items": { "type": "object", "properties": { "@context": { "type": "string" }, "didDocument": { "type": "object", "description": "DID Document contents" }, "didDocumentMetadata": { "type": "object" }, "mdip": { "type": "object" } } } } ] } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/index/export": { "post": { "summary": "Export a paginated DID index snapshot or incremental change batch.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "snapshot", "changes" ] }, "cursor": { "type": "string", "nullable": true, "description": "Opaque snapshot cursor or incremental change cursor." }, "checkpointCursor": { "type": "string", "nullable": true, "description": "Snapshot-only high-water change cursor returned by the first snapshot page and required on continuation pages." }, "limit": { "type": "integer", "minimum": 1 }, "includeOperations": { "type": "boolean", "description": "Changes-only. Include event-level operation records for consumers that need replay order." } } } } } }, "responses": { "200": { "description": "Index export page.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "mode", "indexEpoch", "cursor", "checkpointCursor", "hasMore", "dids", "blocks" ], "properties": { "mode": { "type": "string", "enum": [ "snapshot" ] }, "indexEpoch": { "type": "string", "description": "Local Gatekeeper index epoch. Changes when the backing index database is reset or replaced." }, "cursor": { "type": "string", "nullable": true, "description": "Opaque snapshot page cursor. Clients must store and pass it back without interpretation." }, "checkpointCursor": { "type": "string", "nullable": true, "description": "Snapshot high-water change cursor returned on every snapshot page." }, "hasMore": { "type": "boolean" }, "dids": { "type": "array", "items": { "type": "object" } }, "blocks": { "type": "array", "items": { "type": "object" } } } }, { "type": "object", "required": [ "mode", "indexEpoch", "cursor", "checkpointCursor", "hasMore", "dids", "blocks" ], "properties": { "mode": { "type": "string", "enum": [ "changes" ] }, "indexEpoch": { "type": "string", "description": "Local Gatekeeper index epoch. Changes when the backing index database is reset or replaced." }, "cursor": { "type": "string", "nullable": true, "description": "Incremental change cursor." }, "checkpointCursor": { "type": "string", "nullable": true, "description": "Change high-water cursor returned with the page." }, "hasMore": { "type": "boolean" }, "dids": { "type": "array", "items": { "type": "object" } }, "blocks": { "type": "array", "items": { "type": "object" } }, "operations": { "type": "array", "description": "Optional ordered operation records. Returned only when includeOperations is true.", "items": { "type": "object" } }, "removedOperations": { "type": "array", "description": "Optional ordered operation removals. Returned only when includeOperations is true.", "items": { "type": "object" } } } } ] } } } }, "400": { "description": "Invalid request body.", "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" } } } } } }, "503": { "description": "Gatekeeper database is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/dids/remove": { "post": { "summary": "Remove one or more DIDs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "description": "A valid DID." } } } } }, "responses": { "200": { "description": "Indicates whether the operation succeeded.", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/dids/export": { "post": { "summary": "Export events for one or more DIDs", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "dids": { "type": "array", "description": "A list of DIDs to export. If omitted, all known DIDs are exported.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Returns an array of arrays, where each sub-array contains the event objects for a single DID.", "content": { "application/json": { "schema": { "type": "array", "description": "Each element corresponds to a DID's event list.", "items": { "type": "array", "description": "An array of event objects for a single DID.", "items": { "type": "object", "description": "A single event in the DID's event history.", "properties": { "registry": { "type": "string", "description": "The registry." }, "time": { "type": "string", "format": "date-time", "description": "Timestamp indicating when this event occurred." }, "ordinal": { "oneOf": [ { "type": "integer", "description": "A single integer ordinal (often 0 if unused)" }, { "type": "array", "description": "A tuple of integers for multi-part ordinal keys", "items": { "type": "integer" } } ] }, "operation": { "type": "object", "description": "The DID operation that defines changes." }, "did": { "type": "string", "description": "The DID this event belongs to." } } } } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/dids/import": { "post": { "summary": "Import one or more DIDs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "An array where each item is itself an array of event objects corresponding to a single DID’s history.\n", "items": { "type": "array", "description": "A list of all events that define one DID's state.", "items": { "type": "object", "required": [ "did", "operation", "registry", "time" ], "properties": { "did": { "type": "string", "description": "The DID these events belong to." }, "operation": { "type": "object", "description": "The DID operation including signatures and other data.", "properties": { "type": { "type": "string", "description": "The operation type (\"create\", \"update\", or \"delete\")." }, "created": { "type": "string", "format": "date-time", "description": "Creation timestamp (if `type = \"create\"`)." }, "mdip": { "type": "object", "description": "MDIP metadata." }, "publicJwk": { "type": "object", "description": "Public key in JWK format (required for agent creates)." }, "signature": { "type": "object", "description": "Cryptographic signature" } }, "required": [ "type", "signature" ] }, "registry": { "type": "string", "description": "The registry this event belongs to." }, "time": { "type": "string", "format": "date-time", "description": "Timestamp when this event was recorded." }, "ordinal": { "oneOf": [ { "type": "integer", "description": "A single integer ordinal (often 0 if unused)" }, { "type": "array", "description": "A tuple of integers for multi-part ordinal keys", "items": { "type": "integer" } } ] } } } } } } } }, "responses": { "200": { "description": "Summary of the import operation.", "content": { "application/json": { "schema": { "type": "object", "description": "Object containing counts of how many events were queued, processed (duplicates), rejected, and the current queue total.", "properties": { "queued": { "type": "integer", "description": "Number of new events queued." }, "processed": { "type": "integer", "description": "Number of events recognized as duplicates (already known)." }, "rejected": { "type": "integer", "description": "Number of events that failed validation (bad signature, size limit, etc.)." }, "rejectedIndices": { "type": "array", "description": "Zero-based indexes of rejected events in the original submitted batch order (for importDIDs this is `dids.flat()` order).", "items": { "type": "integer" } }, "total": { "type": "integer", "description": "Total number of events in the queue after this import." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/batch/export": { "post": { "summary": "Export non-local DID events in a single sorted batch", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "dids": { "type": "array", "description": "A list of DIDs to export. If omitted, all known DIDs are used for exporting.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "A single sorted array of all non-local events for the specified DIDs.", "content": { "application/json": { "schema": { "type": "array", "description": "Each item is an event object, sorted by the signature’s signed timestamp.", "items": { "type": "object", "properties": { "registry": { "type": "string", "description": "Registry for this event. Local registry events are excluded." }, "time": { "type": "string", "format": "date-time", "description": "When this event was recorded in the database." }, "ordinal": { "oneOf": [ { "type": "integer", "description": "A single integer ordinal (often 0 if unused)" }, { "type": "array", "description": "A tuple of integers for multi-part ordinal keys", "items": { "type": "integer" } } ] }, "operation": { "type": "object", "description": "Details of the DID operation.", "properties": { "type": { "type": "string", "description": "The operation type." }, "did": { "type": "string", "description": "The DID for which this event applies." }, "signature": { "type": "object", "description": "Cryptographic signature." } } }, "did": { "type": "string", "description": "The DID this event belongs to, generally matching operation.did." } } } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/batch/import": { "post": { "summary": "Import a batch of DID events", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "An array of event objects representing DID operations.", "items": { "type": "object", "required": [ "did", "operation", "registry", "time" ], "properties": { "did": { "type": "string", "description": "The DID to which this event pertains." }, "operation": { "type": "object", "description": "A DID operation, such as \"create\", \"update\", or \"delete\".", "properties": { "type": { "type": "string", "description": "Operation type.", "example": "create" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp when the DID was created (if `type = \"create\"`)." }, "mdip": { "type": "object", "description": "MDIP metadata (type, version, registry)." }, "publicJwk": { "type": "object", "description": "Public key in JWK format, required for \"agent\" creation." }, "signature": { "type": "object", "description": "Cryptographic signature." } } }, "registry": { "type": "string", "description": "The registry to which this event belongs.", "example": "local" }, "time": { "type": "string", "format": "date-time", "description": "Timestamp when the event was recorded." }, "ordinal": { "oneOf": [ { "type": "integer", "description": "A single integer ordinal (often 0 if unused)" }, { "type": "array", "description": "A tuple of integers for multi-part ordinal keys", "items": { "type": "integer" } } ] } } } } } } }, "responses": { "200": { "description": "An object summarizing how many events were queued, processed, rejected, and the current queue size.", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "integer", "description": "Number of new, valid events that were queued." }, "processed": { "type": "integer", "description": "Number of events recognized as duplicates." }, "rejected": { "type": "integer", "description": "Number of events that failed validation." }, "rejectedIndices": { "type": "array", "description": "Zero-based indexes of rejected events in the original submitted batch order.", "items": { "type": "integer" } }, "total": { "type": "integer", "description": "The total event queue size after this import." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/queue/{registry}": { "get": { "summary": "Retrieve the queued events for a specific registry", "parameters": [ { "in": "path", "name": "registry", "required": true, "schema": { "type": "string" }, "description": "The name of the registry whose queue is being retrieved. Valid values may include \"local\", \"hyperswarm\", \"TBTC\", \"TFTC\", etc.\n" } ], "responses": { "200": { "description": "An array of queued event objects for the specified registry.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "An individual event in the queue.", "properties": { "registry": { "type": "string", "description": "The registry to which the event belongs." }, "time": { "type": "string", "format": "date-time", "description": "Timestamp when this event was added to the queue." }, "ordinal": { "oneOf": [ { "type": "integer", "description": "A single integer ordinal (often 0 if unused)" }, { "type": "array", "description": "A tuple of integers for multi-part ordinal keys", "items": { "type": "integer" } } ] }, "operation": { "type": "object", "description": "Details of the DID operation.", "properties": { "type": { "type": "string", "description": "The operation type." }, "did": { "type": "string", "description": "The DID to which this event applies." }, "signature": { "type": "object", "description": "Cryptographic signature." } } }, "did": { "type": "string", "description": "The DID that this queue event references (often identical to `operation.did`)." } } } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/queue/{registry}/clear": { "post": { "summary": "Remove specified DIDs from the queue", "parameters": [ { "in": "path", "name": "registry", "required": true, "schema": { "type": "string" }, "description": "The name of the registry from which events will be cleared. Must be a valid, supported registry.\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "description": "An array of SHA-256 hashes of queued operations to remove.", "items": { "type": "string" } }, { "type": "array", "description": "An array of DID operation event objects to remove from the queue.", "items": { "type": "object", "description": "A queued DID operation event.", "properties": { "type": { "type": "string", "description": "The operation type." }, "did": { "type": "string", "description": "The DID targeted by this operation." }, "doc": { "type": "object", "description": "The (optional) DID document content, present if type is \"update\" or \"create\" with doc data." }, "previd": { "type": "string", "description": "Reference to the previous version for update and delete operations." }, "signature": { "type": "object", "description": "Cryptographic signature." } }, "required": [ "type", "did", "signature" ] } } ] } } } }, "responses": { "200": { "description": "Whether the specified events were cleared successfully.", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/registries": { "get": { "summary": "Retrieve supported registries", "responses": { "200": { "description": "An array of registry names.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/db/reset": { "get": { "summary": "Reset the database", "responses": { "200": { "description": "The database was successfully reset.", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/db/verify": { "get": { "summary": "Verify all DIDs in the database", "responses": { "200": { "description": "Verification results for all DIDs in the database.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "The total number of DIDs that were checked." }, "verified": { "type": "integer", "description": "The count of DIDs that passed verification." }, "expired": { "type": "integer", "description": "The count of DIDs that had expired and were removed." }, "invalid": { "type": "integer", "description": "The count of DIDs that failed verification and were removed." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/events/process": { "post": { "summary": "Process queued events", "description": "Iterates over all queued events, importing them if they are valid (adding or merging). Continues until no more new events can be processed. If `processEvents` is already running, it may return `{ busy: true }` to indicate that processing is in progress.\n", "responses": { "200": { "description": "A summary of how many events were added, merged, rejected, or still pending in the queue. Or `{ busy: true }` if processing is already underway.\n", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "busy": { "type": "boolean", "description": "Indicates that the processing is already in progress." } } }, { "type": "object", "properties": { "added": { "type": "integer", "description": "Number of newly imported events." }, "merged": { "type": "integer", "description": "Number of duplicate events merged." }, "rejected": { "type": "integer", "description": "Number of events that failed validation." }, "pending": { "type": "integer", "description": "Number of events still left in the queue after processing." }, "acceptedHashes": { "type": "array", "description": "Lower-case signature hashes of events accepted during this processing run (added or merged).", "items": { "type": "string" } }, "acceptedEvents": { "type": "array", "description": "Events accepted during this processing run (added or merged).", "items": { "type": "object" } }, "rejectedOperations": { "type": "array", "description": "Operations rejected during this processing run.", "items": { "type": "object" } } } } ] } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/cas/json": { "post": { "summary": "Adds a JSON object to the CAS (Content Addressable Storage)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The JSON object to store in the CAS" }, "responses": { "200": { "description": "A CID (Content Identifier) for the added JSON object in base58btc format\n", "content": { "text/html": { "schema": { "type": "string", "example": "z3v8AuahvBGDMXvCTWedYbxnH6C9ZrsEtEJAvip2XPzcZb8yo6A" } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } }, "503": { "description": "IPFS is disabled. The response body is `IPFS disabled`.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/cas/json/{cid}": { "get": { "summary": "Retrieve a JSON object from the CAS (Content Addressable Storage)", "parameters": [ { "in": "path", "name": "cid", "required": true, "schema": { "type": "string" }, "description": "The CID (Content Identifier) of the JSON object to retrieve" } ], "responses": { "200": { "description": "Successfully retrieved the JSON object", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "text/html": { "schema": { "type": "string" } } } }, "503": { "description": "IPFS is disabled. The response body is `IPFS disabled`.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/cas/text": { "post": { "summary": "Adds text to the CAS (Content Addressable Storage)", "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "The text to store in the CAS" }, "responses": { "200": { "description": "A CID (Content Identifier) for the added text in base58btc format\n", "content": { "text/html": { "schema": { "type": "string", "example": "zb2rhoVn27TzH1yQD1Bux7XKxaUBp3Rwzvd8Re9Shp4bEGokf" } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } }, "503": { "description": "IPFS is disabled. The response body is `IPFS disabled`.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/cas/text/{cid}": { "get": { "summary": "Retrieve text from the CAS (Content Addressable Storage)", "parameters": [ { "in": "path", "name": "cid", "required": true, "schema": { "type": "string" }, "description": "The CID (Content Identifier) of the text to retrieve" } ], "responses": { "200": { "description": "Successfully retrieved the text", "content": { "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "Internal Server Error", "content": { "text/html": { "schema": { "type": "string" } } } }, "503": { "description": "IPFS is disabled. The response body is `IPFS disabled`.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/cas/data": { "post": { "summary": "Adds an octet-stream to the CAS (Content Addressable Storage)", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "description": "The data to store in the CAS" }, "responses": { "200": { "description": "A CID (Content Identifier) for the added data in base58btc format\n", "content": { "text/html": { "schema": { "type": "string", "example": "zdj7WnZAJEYaTTvvDRXCfDpN8raDkX63VrrZBTpV5fw4cVciw" } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } }, "503": { "description": "IPFS is disabled. The response body is `IPFS disabled`.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/cas/data/{cid}": { "get": { "summary": "Retrieve data from the CAS (Content Addressable Storage)", "parameters": [ { "in": "path", "name": "cid", "required": true, "schema": { "type": "string" }, "description": "The CID (Content Identifier) of the data to retrieve" } ], "responses": { "200": { "description": "Successfully retrieved the data", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "description": "Internal Server Error", "content": { "text/html": { "schema": { "type": "string" } } } }, "503": { "description": "IPFS is disabled. The response body is `IPFS disabled`.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/block/{registry}/latest": { "get": { "summary": "Retrieve the latest block for a specific registry", "parameters": [ { "in": "path", "name": "registry", "required": true, "schema": { "type": "string" }, "description": "The name of the registry to retrieve the latest block from." } ], "responses": { "200": { "description": "Successfully retrieved the latest block.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hash": { "type": "string", "description": "The hash of the latest block." }, "height": { "type": "integer", "description": "The height of the latest block." }, "time": { "type": "integer", "description": "The timestamp of the latest block in seconds since the Unix epoch." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/block/{registry}/{blockId}": { "get": { "summary": "Retrieve a specific block for a given registry", "parameters": [ { "in": "path", "name": "registry", "required": true, "schema": { "type": "string" }, "description": "The name of the registry to retrieve the block from." }, { "in": "path", "name": "blockId", "required": true, "schema": { "oneOf": [ { "type": "string", "description": "The hash of the block." }, { "type": "integer", "description": "The height of the block." } ] }, "description": "The identifier of the block to retrieve. Can be either a block hash (string) or a block height (integer).\n" } ], "responses": { "200": { "description": "Successfully retrieved the block.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hash": { "type": "string", "description": "The hash of the block." }, "height": { "type": "integer", "description": "The height of the block." }, "time": { "type": "integer", "description": "The timestamp of the block in seconds since the Unix epoch." }, "timeISO": { "type": "string", "format": "date-time", "description": "The timestamp of the block in ISO 8601 format." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/block/{registry}": { "post": { "summary": "Add a new block to a specific registry", "parameters": [ { "in": "path", "name": "registry", "required": true, "schema": { "type": "string" }, "description": "The name of the registry to which the block will be added." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hash", "height", "time" ], "properties": { "hash": { "type": "string", "description": "The hash of the block." }, "height": { "type": "integer", "description": "The height of the block." }, "time": { "type": "integer", "description": "The timestamp of the block in seconds since the Unix epoch." } } } } } }, "responses": { "200": { "description": "Successfully added the block.", "content": { "application/json": { "schema": { "type": "boolean", "example": true } } } }, "500": { "description": "Internal Server Error.", "content": { "text/html": { "schema": { "type": "string" } } } } } } } }, "components": {}, "tags": [] }