parados/docs/parados.7 at master · uint23/parados · GitHub

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