openapi: 3.0.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.\n\nThis API provides comprehensive endpoints to resolve dPIDs (decentralized Persistent Identifiers) to their corresponding manifests, content, and metadata. It powers both browse and detail page experiences for the decentralized research ecosystem.\n\n## Key Use Cases\n\n### Browse Pages\n- **/api/v2/query/dpids** - Paginated lists of all research objects with optional metadata\n- **Filter & sort** - Find research by recency, metadata fields, version activity  \n- **Performance optimized** - Smart caching and optional metadata resolution\n\n### Detail Pages\n- **/api/v2/resolve/dpid/{id}** - Complete research object with full version history\n- **/api/v2/resolve/{path}** - Flexible access to specific files and versions\n- **Multi-format support** - JSON, raw IPFS, MyST, JSON-LD outputs\n\n### Direct Access\n- **User-friendly URLs** - Handle dpid.org/123 style links\n- **Version navigation** - Access any historical version (v1, v2, etc.)\n- **File-level access** - Direct links to papers, data, code within research objects\n\n## Features\n- **Fast Resolution**: Resolve dPIDs to manifests and content with sub-second response times\n- **Version History**: Complete chronological access to all research object versions\n- **Metadata Enrichment**: Optional IPFS manifest resolution for titles, authors, descriptions\n- **Flexible Formats**: JSON APIs, raw IPFS redirects, MyST Markdown, JSON-LD semantic data\n- **Pagination**: Efficient browsing through large research collections\n- **Smart Caching**: Redis-backed performance optimization\n- **Cross-Protocol**: Works with both Ceramic streams and legacy blockchain contracts\n\n## Common Integration Patterns\n\n**Research Discovery Platform:**\nGET /api/v2/query/dpids?metadata=true&fields=title,authors&size=20\n\n**Research Detail View:**\nGET /api/v2/resolve/dpid/123\nGET /api/v2/resolve/123/manuscript.pdf?format=raw\n\n**Analytics Dashboard:**\nGET /api/v2/query/dpids?history=true&size=100\n\n## Authentication\nThis API is currently public and does not require authentication.\n\n## Rate Limiting\nPlease be mindful of API usage. Rate limits may be applied to prevent abuse.\n\n## Support\nQuestions? Check our GitHub Issues or contact support."
  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
  /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
  /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
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
          nullable: true
          description: File size if known
        type:
          type: string
          enum:
          - file
          - directory
        children:
          type: array
          items:
            $ref: '#/components/schemas/IpfsEntry'