DeSci Labs Data API

openapi: 3.2.0
info:
  title: dPID Resolver Data API
  version: 2.0.0
  description: An open-source HTTP resolver for dPIDs, bridging decentralized protocols to HTTP for scientific research artifact data.
  contact:
    name: API Support
    url: https://github.com/desci-labs/dpid-resolver/issues
    email: support@desci.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: /api
  description: Current Host API
- url: http://localhost:5461/api
  description: Local Development Server
- url: https://dev-beta.dpid.org/api
  description: Development API
- url: https://beta.dpid.org/api
  description: Production API
tags:
- name: Data
  description: '**Data utilities** - IPFS-related utilities like folder tree listing by dPID or CID. Useful for directory browsing UIs and content explorers.'
paths:
  /v2/data/dpid/{dpid}:
    get:
      tags:
      - Data
      summary: Get IPFS folder tree for the research object's root by dPID
      description: 'Resolves the given dPID to its manifest and returns the directory tree for the `root` component''s CID.

        Use `depth` to limit recursion for performance; use `full` for complete traversal.'
      parameters:
      - in: path
        name: dpid
        required: true
        schema:
          type: string
          pattern: ^\d+$
        description: The dPID identifier (numeric)
      - in: query
        name: version
        schema:
          type: string
          example: v3
        description: Specific version index (e.g., `v3` or `2`) to resolve before reading the root CID
      - in: query
        name: concurrency
        schema:
          type: integer
          minimum: 1
          maximum: 16
          default: 8
        description: Maximum number of concurrent DAG fetches
      - in: query
        name: depth
        schema:
          oneOf:
          - type: string
            enum:
            - full
          - type: integer
            minimum: 0
        description: Maximum directory depth to traverse. Use `full` for complete traversal, or a number (0=root only).
      responses:
        '200':
          description: Folder tree
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpfsEntry'
        '400':
          description: Invalid dpid
        '500':
          description: Failed to build folder tree
      operationId: getV2DataDpidByDpid
      x-operation-id-source: derived
  /v2/data/cid/{cid}:
    get:
      tags:
      - Data
      summary: Get IPFS folder tree by root CID
      description: Returns the directory tree for a given UnixFS root CID. Use `depth` to limit recursion for performance; use `full` for a complete traversal.
      parameters:
      - in: path
        name: cid
        required: true
        schema:
          type: string
        description: Root CID of a UnixFS directory or file
      - in: query
        name: rootName
        schema:
          type: string
          default: root
        description: Custom root label in the returned tree
      - in: query
        name: concurrency
        schema:
          type: integer
          minimum: 1
          maximum: 16
          default: 8
        description: Maximum number of concurrent DAG fetches
      - in: query
        name: depth
        schema:
          oneOf:
          - type: string
            enum:
            - full
          - type: integer
            minimum: 0
        description: Maximum directory depth to traverse. Use `full` for complete traversal, or a number (0=root only).
      responses:
        '200':
          description: Folder tree
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpfsEntry'
        '500':
          description: Failed to build folder tree
      operationId: getV2DataCidByCid
      x-operation-id-source: derived
  /v2/data/dpid/{dpid}/*:
    get:
      tags:
      - Data
      summary: Get IPFS folder tree for a specific path within a dPID
      description: 'Resolves the given dPID and navigates to a specific path within the root component.

        For example: /v2/data/dpid/827/root/code will return just the ''code'' directory.'
      parameters:
      - in: path
        name: dpid
        required: true
        schema:
          type: string
        description: The dPID identifier followed by the path (e.g., 827/root/code)
      - in: query
        name: depth
        schema:
          oneOf:
          - type: string
            enum:
            - full
          - type: integer
            minimum: 0
        description: Maximum directory depth to traverse
      responses:
        '200':
          description: Folder tree at the specified path
        '404':
          description: Path not found
      operationId: getV2DataDpidByDpid*
      x-operation-id-source: derived
components:
  schemas:
    IpfsEntry:
      type: object
      required:
      - name
      - path
      - cid
      - type
      properties:
        name:
          type: string
          description: File or directory name
        path:
          type: string
          description: Path from the root label to this entry
        cid:
          type: string
          description: IPFS CID
        size:
          type:
          - integer
          - 'null'
          description: File size if known
        type:
          type: string
          enum:
          - file
          - directory
        children:
          type: array
          items:
            $ref: '#/components/schemas/IpfsEntry'