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: v1.0 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 a DNS-encoded BEP44 record set 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_solution: type: string description: A retention solution calculated according to the spec-defined retention solution algorithm required: [ did, sig, seq, v ] responses: "202": description: The server has accepted the request as valid and will publish it to the DHT content: application/json: schema: type: object properties: expiry: type: number "400": description: Invalid request content: application/json: schema: type: string "401": description: Invalid signature or retention solution 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 "503": description: Retention sets have been temporarily disabled. 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: The DID to resolve required: true schema: type: string - name: seq in: query description: The 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 expiry: type: number description: The Unix Timestamp in seconds indicating when the DID will be evicted from the Gateway's Retained DID Set required: [ did, dht ] "400": description: Invalid request content: application/json: schema: type: string "404": description: The requested 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. The 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 /challenge: get: tags: - DID summary: Get information necessary to solve a retention challenge description: Get information needed to calculate a retention solution for DID PUT operations responses: "200": description: The current hash and difficulty to calculate a retention solution against, along with an estimated retention guarantee represented by the expiry property content: application/json: schema: type: object properties: hash: type: string description: The current hash which is to be used as input for computing a retention solution hash_source: type: string description: The source of the hash as defined by the Hash Source Registry. difficulty: type: integer description: The current difficulty of the challenge representing the number of bits of leading zeros the resulting hash must contain expiry: type: integer description: An approximate expiry date-time value, if a valid Retention Solution is submitted against this challenge, represented as a Unix Timestamp in seconds. The precise expiry date-time value is returned as a part of a PUT operation required: [ hash, difficult, expiry ] "501": description: Retention challenges are not supported content: application/json: schema: type: string "503": description: Retention sets have been temporarily disabled content: application/json: schema: type: string