---
title: "List directory contents"
method: GET
path: "/api/repos/{namespace}/{repo_name}/dir/{resource}"
tags: ["Directories"]
---

# List directory contents

`GET /api/repos/{namespace}/{repo_name}/dir/{resource}`

## Request

- Base URL: `https://hub.oxen.ai`
- URL: `https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/dir/{resource}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/oxen/apis/oxen-server/docs/api/repos/:namespace/:repo_name/dir/:resource/get.ts> (a function with typed inputs; its response is checked against the schema)

List paginated contents of a directory at a specific revision, with optional workspace support.

## Path parameters

- `namespace` string, required
- `repo_name` string, required
- `resource` string, required
- `page` integer, nullable, required
- `page_size` integer, nullable, required
- `api_version` string, nullable, required
- `depth` integer, nullable, required
- `sort_by` string, nullable, required
- `reverse` boolean, nullable, required

## Response `200`

Paginated list of directory entries

- PaginatedDirEntriesResponse
  - `oxen_version` string, nullable
  - `status` string, required
  - `status_message` string, required
  - `dir` union
    - MetadataEntry: `deny_unknown_fields` is the discriminator for the untagged `EMetadataEntry` enum: payloads with a `changes` field (i.e. `WorkspaceMetadataEntry`) fail to deserialize here and fall through to the workspace variant.
      - `children` MetadataEntry[], nullable
      - `data_type` 'dir' | 'text' | 'image' | 'video' | 'audio' | 'tabular' | 'binary', required
      - `extension` string, required
      - `filename` string, required
      - `hash` string, required
      - `is_dir` boolean, required
      - `is_queryable` boolean, nullable
      - `latest_commit` Commit
        - `author` string, required
        - `email` string, required
        - `id` string, required
        - `message` string, required
        - `parent_ids` string[], required
        - `timestamp` string, date-time, required
      - `metadata` union
        - MetadataDir
          - `dir` MetadataDirImpl, required
            - `data_types` DataTypeCount[], required
              - …
        - MetadataText
          - `text` MetadataTextImpl, required
            - `num_chars` integer, required
            - `num_lines` integer, required
        - MetadataImage
          - `image` MetadataImageImpl, required
            - `color_space` 'RGB' | 'RGBA' | 'Grayscale' | 'GrayscaleAlpha' | 'Rgb16' | 'Rgba16' | 'Grayscale16' | 'GrayscaleAlpha16' | 'Rgb32F' | 'Rgba32F' | 'Unknown'
            - `height` integer, required
            - `width` integer, required
        - MetadataVideo
          - `video` MetadataVideoImpl, required
            - `height` integer, required
            - `num_seconds` number, double, required
            - `width` integer, required
        - MetadataAudio
          - `audio` MetadataAudioImpl, required
            - `num_channels` integer, required
            - `num_seconds` number, double, required
            - `sample_rate` integer, required
        - MetadataTabular
          - `tabular` MetadataTabularImpl, required
            - `height` integer, required
            - `schema` Schema, required
              - …
            - `width` integer, required
      - `mime_type` string, required
      - `resource` ParsedResourceView: External (view) model that is returned to the client with fewer fields.
        - `branch` Branch
          - `commit_id` string, required
          - `name` string, required
        - `commit` Commit
          - `author` string, required
          - `email` string, required
          - `id` string, required
          - `message` string, required
          - `parent_ids` string[], required
          - `timestamp` string, date-time, required
        - `path` string, required
        - `resource` string, required
        - `version` string, required
        - `workspace` WorkspaceView: Used to send workspace state across the wire. The `Workspace`'s other fields (like `LocalRepository`) would bloat the response and leak internal state.
          - `commit` Commit, required
            - `author` string, required
            - `email` string, required
            - `id` string, required
            - `message` string, required
            - `parent_ids` string[], required
            - `timestamp` string, date-time, required
          - `created_at` string, date-time, nullable: `None` for a workspace created before the server recorded creation time.
          - `id` string, required
          - `name` string, nullable
      - `size` integer, required
    - WorkspaceMetadataEntry
      - `changes` WorkspaceChanges
        - `status` 'Added' | 'Modified' | 'Removed' | 'Unmodified', required
      - `children` WorkspaceMetadataEntry[], nullable
      - `data_type` 'dir' | 'text' | 'image' | 'video' | 'audio' | 'tabular' | 'binary', required
      - `extension` string, required
      - `filename` string, required
      - `hash` string, required
      - `is_dir` boolean, required
      - `is_queryable` boolean, nullable
      - `latest_commit` Commit
        - `author` string, required
        - `email` string, required
        - `id` string, required
        - `message` string, required
        - `parent_ids` string[], required
        - `timestamp` string, date-time, required
      - `metadata` union
        - MetadataDir
          - `dir` MetadataDirImpl, required
            - `data_types` DataTypeCount[], required
              - …
        - MetadataText
          - `text` MetadataTextImpl, required
            - `num_chars` integer, required
            - `num_lines` integer, required
        - MetadataImage
          - `image` MetadataImageImpl, required
            - `color_space` 'RGB' | 'RGBA' | 'Grayscale' | 'GrayscaleAlpha' | 'Rgb16' | 'Rgba16' | 'Grayscale16' | 'GrayscaleAlpha16' | 'Rgb32F' | 'Rgba32F' | 'Unknown'
            - `height` integer, required
            - `width` integer, required
        - MetadataVideo
          - `video` MetadataVideoImpl, required
            - `height` integer, required
            - `num_seconds` number, double, required
            - `width` integer, required
        - MetadataAudio
          - `audio` MetadataAudioImpl, required
            - `num_channels` integer, required
            - `num_seconds` number, double, required
            - `sample_rate` integer, required
        - MetadataTabular
          - `tabular` MetadataTabularImpl, required
            - `height` integer, required
            - `schema` Schema, required
              - …
            - `width` integer, required
      - `mime_type` string, required
      - `resource` ParsedResourceView: External (view) model that is returned to the client with fewer fields.
        - `branch` Branch
          - `commit_id` string, required
          - `name` string, required
        - `commit` Commit
          - `author` string, required
          - `email` string, required
          - `id` string, required
          - `message` string, required
          - `parent_ids` string[], required
          - `timestamp` string, date-time, required
        - `path` string, required
        - `resource` string, required
        - `version` string, required
        - `workspace` WorkspaceView: Used to send workspace state across the wire. The `Workspace`'s other fields (like `LocalRepository`) would bloat the response and leak internal state.
          - `commit` Commit, required
            - `author` string, required
            - `email` string, required
            - `id` string, required
            - `message` string, required
            - `parent_ids` string[], required
            - `timestamp` string, date-time, required
          - `created_at` string, date-time, nullable: `None` for a workspace created before the server recorded creation time.
          - `id` string, required
          - `name` string, nullable
      - `size` integer, required
  - `entries` EMetadataEntry[], required
    - union
      - MetadataEntry: `deny_unknown_fields` is the discriminator for the untagged `EMetadataEntry` enum: payloads with a `changes` field (i.e. `WorkspaceMetadataEntry`) fail to deserialize here and fall through to the workspace variant.
        - `children` MetadataEntry[], nullable
        - `data_type` 'dir' | 'text' | 'image' | 'video' | 'audio' | 'tabular' | 'binary', required
        - `extension` string, required
        - `filename` string, required
        - `hash` string, required
        - `is_dir` boolean, required
        - `is_queryable` boolean, nullable
        - `latest_commit` Commit
          - `author` string, required
          - `email` string, required
          - `id` string, required
          - `message` string, required
          - `parent_ids` string[], required
          - `timestamp` string, date-time, required
        - `metadata` union
          - MetadataDir
            - `dir` MetadataDirImpl, required
              - …
          - MetadataText
            - `text` MetadataTextImpl, required
              - …
          - MetadataImage
            - `image` MetadataImageImpl, required
              - …
          - MetadataVideo
            - `video` MetadataVideoImpl, required
              - …
          - MetadataAudio
            - `audio` MetadataAudioImpl, required
              - …
          - MetadataTabular
            - `tabular` MetadataTabularImpl, required
              - …
        - `mime_type` string, required
        - `resource` ParsedResourceView: External (view) model that is returned to the client with fewer fields.
          - `branch` Branch
            - `commit_id` string, required
            - `name` string, required
          - `commit` Commit
            - `author` string, required
            - `email` string, required
            - `id` string, required
            - `message` string, required
            - `parent_ids` string[], required
            - `timestamp` string, date-time, required
          - `path` string, required
          - `resource` string, required
          - `version` string, required
          - `workspace` WorkspaceView: Used to send workspace state across the wire. The `Workspace`'s other fields (like `LocalRepository`) would bloat the response and leak internal state.
            - `commit` Commit, required
              - …
            - `created_at` string, date-time, nullable: `None` for a workspace created before the server recorded creation time.
            - `id` string, required
            - `name` string, nullable
        - `size` integer, required
      - WorkspaceMetadataEntry
        - `changes` WorkspaceChanges
          - `status` 'Added' | 'Modified' | 'Removed' | 'Unmodified', required
        - `children` WorkspaceMetadataEntry[], nullable
        - `data_type` 'dir' | 'text' | 'image' | 'video' | 'audio' | 'tabular' | 'binary', required
        - `extension` string, required
        - `filename` string, required
        - `hash` string, required
        - `is_dir` boolean, required
        - `is_queryable` boolean, nullable
        - `latest_commit` Commit
          - `author` string, required
          - `email` string, required
          - `id` string, required
          - `message` string, required
          - `parent_ids` string[], required
          - `timestamp` string, date-time, required
        - `metadata` union
          - MetadataDir
            - `dir` MetadataDirImpl, required
              - …
          - MetadataText
            - `text` MetadataTextImpl, required
              - …
          - MetadataImage
            - `image` MetadataImageImpl, required
              - …
          - MetadataVideo
            - `video` MetadataVideoImpl, required
              - …
          - MetadataAudio
            - `audio` MetadataAudioImpl, required
              - …
          - MetadataTabular
            - `tabular` MetadataTabularImpl, required
              - …
        - `mime_type` string, required
        - `resource` ParsedResourceView: External (view) model that is returned to the client with fewer fields.
          - `branch` Branch
            - `commit_id` string, required
            - `name` string, required
          - `commit` Commit
            - `author` string, required
            - `email` string, required
            - `id` string, required
            - `message` string, required
            - `parent_ids` string[], required
            - `timestamp` string, date-time, required
          - `path` string, required
          - `resource` string, required
          - `version` string, required
          - `workspace` WorkspaceView: Used to send workspace state across the wire. The `Workspace`'s other fields (like `LocalRepository`) would bloat the response and leak internal state.
            - `commit` Commit, required
              - …
            - `created_at` string, date-time, nullable: `None` for a workspace created before the server recorded creation time.
            - `id` string, required
            - `name` string, nullable
        - `size` integer, required
  - `metadata` MetadataDir
    - `dir` MetadataDirImpl, required
      - `data_types` DataTypeCount[], required
        - `count` integer, required
        - `data_type` string, required
  - `page_number` integer, required
  - `page_size` integer, required
  - `resource` ResourceVersion
    - `path` string, required
    - `version` string, required
  - `total_entries` integer, required
  - `total_pages` integer, required

## Other responses

- `404`: Directory or repository not found

---

[API](https://skmtc.dev/oxen/apis/oxen-server.md) - [All operations](https://skmtc.dev/oxen/apis/oxen-server/llms.txt) - [OpenAPI document](https://skmtc.dev/oxen/apis/oxen-server/revisions/2ae578129949?raw)