Resolving an IPNS Name

How to obtain an IPFS CID from an IPNS name.

The resolution of IPNS names takes place across two different requests, first a request to initiate the IPNS name resolution, and second a request to check the resolution status that returns the results when available. The IPNS resolution requests are used to obtain the IPFS CID a provided IPNS name points to.

Start Resolution

Overview

The IPNS Resolution Initiation Request, a POST request to the /ipns/resolve endpoint, is a request used to initiate the IPNS name resolution process. This request is the first of two required for resolving IPNS names, with the Check Resolution Status section of this page describing the second part required for resolving IPNS names.

Request Spec

  /ipns/resolve/{name}:
    post:
      summary: Submit an IPNS name for resolution into an IPFS CID. Returns a taskID, and cached CID if available.
      parameters:
        - in: path
          name: name
          required: true
          description: An IPNS name (a mutable pointer to an IPFS CID).
          schema:
            type: string

Sending the Request

Sending a request to the /ipns/resolve endpoint requires a valid API Key to be provided in the x-api-key header, and that an IPNS name be provided.

IPNS Resolution Init. Request

curl -X POST -H "x-api-key: Your-API-Key" https://api.sgr-a.xyz/ipns/resolve/12D3KooWGeC5yANGXWsr6n7zXCFzC2967qeiigdnCJnNFnSqF7CB

When an IPNS Resolution Initiation Request completes successfully, the returned output will contain a confirmation message that the resolution has been initiated, along with a taskId to use in the IPNS Resolution Status Request.

Initiation Output

{
    "taskId": "Assigned-Task-ID",
    "message": "No cached CID found. Your IPNS resolution request is being processed.",
    "cachedCID": null
}

In some cases when an IPNS Resolution Initiation Request is completed, a cached CID from a previous resolution request for the given IPNS name will be included.

Initiation Output

{
    "taskId": "Assigned-Task-ID",
    "message": "Cached CID found. Your IPNS resolution request is being processed.",
    "cachedCID": "QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u"
}

Check Resolution Status

Overview

The IPNS Resolution Status Request, a GET request to the /ipns/result endpoint, is a request used to check the status of an initiated IPNS name resolution, and obtain the resolved IPFS CID when resolution is completed. This request is the second of two required for resolving IPNS names, with the Start Resolution section of this page describing the first part required for initiating the resolution.

Request Spec

  /ipns/result/{taskId}:
    get:
      summary: Request the status of an IPNS name resolution.
      parameters:
        - in: path
          name: taskId
          required: true
          description: A unique identifier for the resolution process of an IPNS name.
          schema:
            type: string

Sending the Request

Sending a request to the /ipns/result endpoint requires a valid API Key to be provided in the x-api-key header, and that a taskId from an IPNS Resolution initiation be provided.

IPNS Resolution Stat. Request

curl -X GET -H "x-api-key: Your-API-Key" https://api.sgr-a.xyz/ipns/result/a1b2c3d4-5678-90ab-cdef-0123456789ab

When an IPNS Resolution Status Request completes successfully while the IPNS name associated with the provided taskId is still in progress for resolution, a message will be provided in the output stating such.

Status Output - In Progress

{
    "message": "IPNS resolution is in progress. Please try again in a moment."
}

When an IPNS Resolution Status Request completes successfully and the IPNS name associated with the provided taskId has completed resolution, a confirmation message stating completion and the resolved CID will be provided in the output.

Status Output - Completed

{
    "status": "completed",
    "result": "QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u"
}