openapi: 3.0.1 info: title: DID DHT Gateway API description: "The [DID DHT API](https://did-dht.com)" license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: v0.1 paths: /{id}: get: tags: - DHT summary: Get DNS-encoded BEP44 records from the DHT description: Get a DNS-encoded BEP44 record set from the DHT parameters: - name: id in: path description: ID to get required: true schema: type: string responses: "200": description: "64 bytes sig, 8 bytes u64 big-endian seq, 0-1000 bytes of v." content: application/octet-stream: schema: type: array items: type: integer "400": description: Bad request content: application/json: schema: type: string "404": description: Not found content: application/json: schema: type: string "500": description: Internal server error content: application/json: schema: type: string put: tags: - DHT summary: Put DNS-encoded BEP44 records into the DHT description: Put a DNS-encoded BEP44 record set into the DHT parameters: - name: id in: path description: ID to put required: true schema: type: string requestBody: description: "64 bytes sig, 8 bytes u64 big-endian seq, 0-1000 bytes of v." content: application/octet-stream: schema: type: array items: type: integer required: true responses: "200": description: OK "400": description: Bad request content: application/json: schema: type: string "500": description: Internal server error content: application/json: schema: type: string /dids/{id}: put: tags: - DID summary: Publish a DID description: Register or Update a DID in the DHT parameters: - name: id in: path description: DID to publish. required: true schema: type: string requestBody: description: A deconstructed DNS-encoded BEP44 request object content: application/json: schema: type: object properties: sig: type: string description: A base64URL-encoded signature of the BEP44 payload. seq: type: integer description: A sequence number for the request, recommended to be a unix timestamp in seconds. v: type: string description: A base64URL-encoded bencoded DNS packet containing the DID Document. retention_proof: type: string description: A retention proof calculated according to the spec-defined retention proof algorithm. required: [ did, sig, seq, v ] responses: "202": description: Accepted. The server has accepted the request as valid and will publish it to the content: application/json: schema: type: string "400": description: Invalid request. content: application/json: schema: type: string "401": description: Invalid signature. content: application/json: schema: type: string "409": description: DID already exists with a higher sequence number. May still be accepted if the Gateway supports historical resolution. content: application/json: schema: type: string get: tags: - DID summary: Resolve a DID description: Resolve a DID from the DHT first, with a fallback to local storage. parameters: - name: id in: path description: DID to resolve. required: true schema: type: string - name: seq in: query description: Sequence number of the DID to resolve. required: false schema: type: integer responses: "200": description: The resolved DID Document. content: application/json: schema: type: object properties: did: type: object description: "The DID Document." dht: type: string description: "An unpadded base64URL-encoded representation of a full DNS-encoded BEP44 payload, represented as 64 bytes sig, 8 bytes u64 big-endian seq, 0-1000 bytes of v concatenated; enabling independent verification." types: type: array items: type: integer description: "The types associated with the DID." sequence_numbers: type: array items: type: integer description: "The sequence numbers available for querying for this node." required: [ did, dht ] "400": description: Invalid request. content: application/json: schema: type: string "404": description: DID could not be resolved. content: application/json: schema: type: string /dids/types: get: tags: - DID summary: Retrieve a list of supported types for indexing. description: Retrieve a list of supported indexing types, according to the spec-defined type list. responses: "200": description: A list of types support, alongside their human-readable description. content: application/json: schema: type: array items: type: object properties: type: type: integer description: type: string required: [ type, description ] "404": description: Type indexing not supported by this gateway. content: application/json: schema: type: string /dids/types/{id}: get: tags: - DID summary: Retrieve a list of DIDs indexed under a given type. description: Retrieve a list of DIDs indexed under a given type, according to the spec-defined type index. parameters: - name: id in: path description: Type to query. required: true schema: type: integer - name: offset in: query description: Specifies the starting position from where the type records should be retrieved. Default is 0. schema: type: integer - name: limit in: query description: Specifies the maximum number of type records to retrieve. Default is 100. schema: type: integer responses: "200": description: A list of DIDs indexed under the given type. content: application/json: schema: type: array items: type: string "404": description: Type not found. content: application/json: schema: type: string /difficulty: get: tags: - DID summary: Get information about the current difficulty. description: Get information needed to calculate a retention proof for DID PUT operations. responses: "200": description: The current hash and difficulty to calculate a retention proof against. content: application/json: schema: type: object properties: hash: type: string difficulty: type: integer required: [ hash, difficulty ] "404": description: Retention proofs not supported by this gateway. content: application/json: schema: type: string