1.Dd January 31, 2026
  2.Dt PARADOS 7
  3.Os
  4.Sh NAME
  5.Nm parados
  6.Nd HTTP protocol for the parados media server
  7.Sh DESCRIPTION
  8The
  9.Nm
 10protocol describes the HTTP interface provided by
 11.Xr parados 1 .
 12It is intended for simple clients and scripts.
 13.Pp
 14The protocol uses HTTP/1.1.
 15Each request is handled on a separate connection, which is
 16closed after the response. Persistent connections are not
 17supported.
 18.Pp
 19Media items are identified by 64-bit identifiers encoded as
 2016 hexadecimal digits.
 21.Sh REQUESTS
 22All endpoints accept
 23.Cm GET
 24and
 25.Cm HEAD
 26requests.
 27The server also accepts
 28.Cm OPTIONS
 29for CORS preflight.
 30.Sh AUTHENTICATION
 31If one or more users are configured,
 32HTTP Basic authentication is required for all endpoints
 33except
 34.Pa /ping .
 35.Pp
 36Credentials are provided using the
 37.Cm Authorization
 38header.
 39.Pp
 40If no users are configured, authentication is disabled.
 41.Pp
 42If
 43.Ic auth_delay
 44is configured in
 45.Xr parados.conf 5 ,
 46unauthorized responses may be intentionally delayed.
 47.Sh ENDPOINTS
 48.Bl -tag -width Ds
 49.It Pa /ping
 50Health check endpoint.
 51Returns HTTP 200 with a short plain text body.
 52.It Pa /library
 53Return the media library as JSON.
 54Each entry contains an item identifier and a relative path.
 55.Pp
 56Response format:
 57.Bd -literal -offset indent
 58{ "proto": 1, "items": [ { "id": "...", "path": "..." } ] }
 59.Ed
 60.It Pa /meta/{id}
 61Return metadata for a single item as JSON.
 62The response includes the item identifier, path, basename,
 63size in bytes, modification time (epoch seconds), MIME type,
 64and kind.
 65.Pp
 66Response format:
 67.Bd -literal -offset indent
 68{ "proto": 1, "id": "...", "path": "...", "name": "...",
 69  "size": N, "mtime": N, "type": "...", "kind": "..." }
 70.Ed
 71.It Pa /stream/{id}
 72Stream the contents of a media item.
 73Supports byte range requests using the
 74.Cm Range
 75header.
 76.Pp
 77Valid ranges return HTTP 206.
 78Invalid ranges return HTTP 400 or HTTP 416.
 79.It Pa /rescan
 80Rescan the media directory and rebuild the library.
 81If authentication is disabled, the endpoint returns HTTP 403.
 82.Pp
 83During a rescan, requests that access the library may get
 84block until the rescan completes.
 85.El
 86.Sh RESPONSES
 87The server sets
 88.Cm Content-Type
 89based on file extension.
 90Unknown types default to
 91.Cm application/octet-stream .
 92.Pp
 93Responses include
 94.Cm Content-Length
 95and close the connection after each request.
 96.Pp
 97If a user is authenticated, items outside the configured
 98allow-list are treated as not found.
 99.Sh STATUS CODES
100.Bl -tag -width Ds
101.It Cm 200
102Request succeeded.
103.It Cm 204
104No content.
105.It Cm 206
106Partial content.
107.It Cm 400
108Bad request.
109.It Cm 401
110Authentication required or failed.
111.It Cm 403
112Forbidden.
113.It Cm 404
114Resource not found or not permitted.
115.It Cm 405
116Method not allowed.
117.It Cm 416
118Requested range not satisfiable.
119.It Cm 500
120Internal server error.
121.El
122.Sh VERSIONING
123JSON responses include a
124.Cm proto
125field indicating the protocol version.
126Clients should reject unknown versions.
127.Sh NOTES
128The protocol does not provide sessions, persistent
129connections, transcoding, or server-side state. All
130higher-level behavior is handled by the client.
131.Sh SEE ALSO
132.Xr parados 1 ,
133.Xr parados.conf 5
134.Sh AUTHORS
135.An Abhinav Prasai
136