> For the complete documentation index, see [llms.txt](https://docs.desci.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.desci.com/technical-background/open-state-repository/pid.md).

# PID

The dPID system for research objects allows resolution to the underlying components in a consistent and granular way over HTTP and the IPFS network. You can learn more about the schema, syntax and variants below. Note that the system is under active development, and the specification is subject to change.

CID refers to Content Identifier according to the [Multiformats CID Specification](https://github.com/multiformats/cid)

## **dPID anatomy**

`HTTP URL = {Resolver}/{PID}/{version identifier OR CID}/{Component index}/{Component suffix}`

<table><thead><tr><th width="230">Component</th><th>Component Description</th></tr></thead><tbody><tr><td>Resolver</td><td>The <a href="https://en.wikipedia.org/wiki/Domain_Name_System">DNS</a> resolver, currently beta.dpid.org</td></tr><tr><td>PID</td><td>The registry's unique and version-invariant PID</td></tr><tr><td>Version identifier or CID</td><td>The version identifier (e.g. "v1" or "0") mapped to the CID of the manifest file or the manifest CID</td></tr><tr><td>Component index</td><td>The index of the component in the research object's data model, or the component ID</td></tr><tr><td>Component suffix</td><td><a href="https://github.com/json-path/JsonPath">JSONPath</a> to manifest component. Encoded with slashes and compact format for URL friendliness.</td></tr></tbody></table>

**Example dPID Links for Data Access**

<table><thead><tr><th width="184">Type</th><th>Link</th></tr></thead><tbody><tr><td>Web</td><td><a href="https://beta.dpid.org/46">https://beta.dpid.org/46</a></td></tr><tr><td>Metadata</td><td><a href="https://beta.dpid.org/46?jsonld">https://beta.dpid.org/46?jsonld</a> and <a href="https://beta.dpid.org/46?raw">https://beta.dpid.org/46?raw</a></td></tr><tr><td>Past Metadata</td><td><a href="https://beta.dpid.org/46?raw">https://beta.dpid.org/46/v1?raw</a></td></tr><tr><td>Code</td><td><a href="https://beta.dpid.org/46/3/root/exploring-lupus/casa/J15430131-3409153_cont.py?raw">https://beta.dpid.org/46/3/root/exploring-lupus/casa/J15430131-3409153_cont.py?raw</a></td></tr><tr><td>Data</td><td><a href="https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt?raw">https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt?raw</a></td></tr></tbody></table>

**Note:** Excluding `?raw` results in resolving the human-accessible data in the Nodes App or another configured resolver application.

**API for Research Objects**

<table><thead><tr><th>Route</th><th>Behavior</th></tr></thead><tbody><tr><td>GET https://beta.dpid.org/api/v1/dpid</td><td><p>List all registered research objects</p><p></p><p>Query Params</p><p><code>page: number = 1 // first page</code></p><p><code>size: number = 100 // 100 items</code></p><p><code>sort: "asc" | "desc" = "desc" // sort descending</code></p><h4>Response</h4><pre class="language-json" data-overflow="wrap"><code class="lang-json">{
    "dpid": "54",
    "id": "0x0...",
    "recentCid": "bafkre...",
    "researchObject": {
        "id": "0x0...",
        "versions": [
            {
                "id": "0x0...",
                "time": 1685098464,
                "cid": "bafkre...",
            },
            {
                "id": "0x0...",
                "time": 1685098776,
                "cid": "bafkre...",
            }
        ]
    }
}
</code></pre></td></tr><tr><td>GET https://beta.dpid.org/46/v1?raw</td><td>Get metadata for specific version of specific research object (application format)<br><br>Response Typescript specification: <a href="https://github.com/desci-labs/nodes/blob/develop/desci-models/src/ResearchObject.ts">https://github.com/desci-labs/nodes/blob/develop/desci-models/src/ResearchObject.ts</a></td></tr><tr><td>GET https://beta.dpid.org/46/v1?jsonld</td><td>Get metadata for specific version of specific research object (semantic format)<br><br>Returns in <a href="https://www.researchobject.org/ro-crate/1.1/">RO-Crate 1.1 format</a><br><br>Response Typescript specification: <br><a href="https://github.com/desci-labs/nodes/blob/develop/desci-models/src/RoCrate.ts">https://github.com/desci-labs/nodes/blob/develop/desci-models/src/RoCrate.ts</a></td></tr></tbody></table>

**Navigating Data via dPID API**

| Route                                                                                                                                                                                                                                                                                                                   | Behavior                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>GET <a href="https://beta.dpid.org/46/root?raw"><https://beta.dpid.org/46/root?raw></a><br>GET <a href="https://beta.dpid.org/46/v1/root?raw"><https://beta.dpid.org/46/v1/root?raw></a><br><br><code>deprecated</code><br>GET <https://beta.dpid.org/46/data?raw><br>GET <https://beta.dpid.org/46/v1/data?raw></p> | These all do the same thing. Get the [DAG-JSON](https://ipld.io/docs/codecs/known/dag-json/) encoded content of the root data folder. If version specified, uses that version, otherwise uses latest version. |
| GET <https://beta.dpid.org/46/root/exploring-lupus-report.pdf?raw>                                                                                                                                                                                                                                                      | Download the specific file specified, if not a file, but a folder, the DAG-JSON encoded content is shown                                                                                                      |

**Valid PID syntax and variants**

There are three different and valid variants of the PIDs that can be resolved over HTTP. These variants offer different levels of friendliness for humans.&#x20;

<table><thead><tr><th width="107.33333333333331">Variant types</th><th width="318">Variant syntax (human)</th><th>Variant syntax (machine)</th></tr></thead><tbody><tr><td>Short form URL variant <br>(<strong>recommended</strong>)</td><td><a href="https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt">https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt</a></td><td><a href="https://beta.dpid.org/46/v4/data/exploring-lupus/output/data_lup.txt?raw">https://beta.dpid.org/46/v4/data/exploring-lupus/output/data_lup.txt?raw</a></td></tr><tr><td>Short form URL variant 0-index<span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span><br><code>deprecated</code></td><td><a href="https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt"><em><mark style="color:blue;">https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt</mark></em></a></td><td><a href="https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt?raw">https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt?raw</a></td></tr><tr><td>Long form URL <span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> <strong>coming soon</strong></td><td><em><mark style="color:blue;">dpid.org/42/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/1/measurements.csv</mark></em></td><td><em><mark style="color:blue;">dpid.org/42/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/1/measurements.csv?raw</mark></em></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.desci.com/technical-background/open-state-repository/pid.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.