API Reference

dir-browser provides a lightweight HTTP API that allows you to retrieve directory listings and file metadata in JSON format. These endpoints are useful for building custom frontends or integrating with other services.

Folder Listing (?ls)

To retrieve the contents of a directory as a JSON array, append ?ls to any folder URL.

Example Request: https://dir-demo.adriansoftware.de/?ls

Response Format:

[
  {
    "url": "/src",
    "name": "src",
    "type": "dir",
    "size": 0,
    "modified": "2024-06-04T16:41:55Z",
    "downloads": 0
  },
  {
    "url": "/dir-browser.png",
    "name": "dir-browser.png",
    "type": "file",
    "size": 810266,
    "modified": "2024-06-04T16:41:55Z",
    "downloads": 51
  },
  {
    "url": "/Dockerfile",
    "name": "Dockerfile",
    "type": "file",
    "size": 1363,
    "modified": "2024-06-04T16:41:55Z",
    "downloads": 242
  },
]

File Information (?info)

To retrieve detailed metadata for a specific file, append ?info to the file URL.

Example Request: https://dir-demo.adriansoftware.de/Dockerfile?info

Response Format:

{
  "url": "/Dockerfile",
  "name": "Dockerfile",
  "mime": "text/plain",
  "size": 1363,
  "modified": 1717519315,
  "downloads": 242,
  "hash_sha256": "8102c6372ce8afd35c87df8a78cbd63386538211f45c0042b1a9a7e73630a9bb"
}

File Preview (?preview)

The ?preview endpoint returns file metadata along with a content snippet for supported text-based files. This endpoint is used by the built-in popup previewer and does not increment the download counter.

Example Request: https://dir-demo.adriansoftware.de/README.md?preview

Response Format:

{
  "url": "/.example.env",
  "name": ".example.env",
  "mime": "text/plain",
  "size": 75,
  "size_human": "75.00 B",
  "modified": "2024-06-04T16:41:55Z",
  "downloads": 159,
  "preview": {
    "kind": "text",
    "mime": "text/plain",
    "truncated": false,
    "text": "# DISPLAY_ERRORS=Off\n# HASH=false\n# HASH_ALGO=md5\n# API=false\n#LAYOUT=popup"
  }
}

Raw Content (?raw)

The ?raw endpoint serves the file's raw content directly. Similar to ?preview, it does not increment the download counter. This is primarily used for embedding media (images, videos, audio) in previews without affecting download statistics.

Example Request: https://dir-demo.adriansoftware.de/Dockerfile?raw

Configuration

The API endpoints can be enabled or disabled using the API environment variable. The ?ls and ?info endpoints require the API environment variable to be set to true.

⚙️ Configuration

Variable	Default	Values	Details
API	true	true false	added in v3.1

How to set configuration options

Set the environment variables when starting the container.
Use docker run...

• ...with -e API=true
• ...with --env-file .env and place API=true in the file

See installation page for more details.