master uint/parados / docs / parados.7
PARADOS(7) Miscellaneous Information Manual PARADOS(7)

parados — HTTP protocol for the parados media server

The parados protocol describes the HTTP interface provided by parados(1). It is intended for simple clients and scripts.

The protocol uses HTTP/1.1. Each request is handled on a separate connection, which is closed after the response. Persistent connections are not supported.

Media items are identified by 64-bit identifiers encoded as 16 hexadecimal digits.

All endpoints accept GET and HEAD requests. The server also accepts OPTIONS for CORS preflight.

If one or more users are configured, HTTP Basic authentication is required for all endpoints except /ping.

Credentials are provided using the Authorization header.

If no users are configured, authentication is disabled.

If auth_delay is configured in parados.conf(5), unauthorized responses may be intentionally delayed.

/ping
Health check endpoint. Returns HTTP 200 with a short plain text body.
/library
Return the media library as JSON. Each entry contains an item identifier and a relative path.

Response format:

{ "proto": 1, "items": [ { "id": "...", "path": "..." } ] }
/meta/{id}
Return metadata for a single item as JSON. The response includes the item identifier, path, basename, size in bytes, modification time (epoch seconds), MIME type, and kind.

Response format:

{ "proto": 1, "id": "...", "path": "...", "name": "...",
  "size": N, "mtime": N, "type": "...", "kind": "..." }
/stream/{id}
Stream the contents of a media item. Supports byte range requests using the Range header.

Valid ranges return HTTP 206. Invalid ranges return HTTP 400 or HTTP 416.

/rescan
Rescan the media directory and rebuild the library. If authentication is disabled, the endpoint returns HTTP 403.

During a rescan, requests that access the library may get block until the rescan completes.

The server sets Content-Type based on file extension. Unknown types default to application/octet-stream.

Responses include Content-Length and close the connection after each request.

If a user is authenticated, items outside the configured allow-list are treated as not found.

Request succeeded.
No content.
Partial content.
Bad request.
Authentication required or failed.
Forbidden.
Resource not found or not permitted.
Method not allowed.
Requested range not satisfiable.
Internal server error.

JSON responses include a proto field indicating the protocol version. Clients should reject unknown versions.

The protocol does not provide sessions, persistent connections, transcoding, or server-side state. All higher-level behavior is handled by the client.

parados(1), parados.conf(5)

Abhinav Prasai

January 31, 2026 Linux 6.18.35-0-lts