BlueGit

timfa filemanager

Files

filemanager / docs / openapi.json

openapi.json

openapi.json 26.0 KiB Download Raw
1{
2 "openapi": "3.0.3",
3 "info": {
4 "title": "Filemanager sync API",
5 "version": "1.0.0",
6 "description": "Versioned API for sync clients (phone, desktop, services). See docs/api.md for the OAuth flow and a sync walkthrough. A token can never see or change more than its user can in the web UI."
7 },
8 "servers": [
9 {
10 "url": "/api/v1"
11 }
12 ],
13 "components": {
14 "securitySchemes": {
15 "oauth2": {
16 "type": "oauth2",
17 "description": "Authorization code with PKCE (S256), public clients without secret.",
18 "flows": {
19 "authorizationCode": {
20 "authorizationUrl": "/oauth/authorize",
21 "tokenUrl": "/oauth/token",
22 "refreshUrl": "/oauth/token",
23 "scopes": {
24 "files:read": "Read and download files",
25 "files:write": "Upload, create, move and delete (implies files:read)"
26 }
27 }
28 }
29 },
30 "personalToken": {
31 "type": "http",
32 "scheme": "bearer",
33 "description": "Personal access token (fmp_...) created on /apps.html"
34 }
35 },
36 "schemas": {
37 "Error": {
38 "type": "object",
39 "required": [
40 "error",
41 "message"
42 ],
43 "properties": {
44 "error": {
45 "type": "string",
46 "example": "conflict"
47 },
48 "message": {
49 "type": "string"
50 },
51 "current": {
52 "allOf": [
53 {
54 "$ref": "#/components/schemas/Entry"
55 }
56 ],
57 "nullable": true,
58 "description": "Current state of the target on 409/412"
59 },
60 "offset": {
61 "type": "integer",
62 "description": "Server offset on upload offset errors"
63 }
64 }
65 },
66 "Entry": {
67 "type": "object",
68 "properties": {
69 "id": {
70 "type": "string",
71 "description": "Stable id (device+inode); survives renames and moves"
72 },
73 "path": {
74 "type": "string",
75 "example": "/~/Photos/a.jpg"
76 },
77 "name": {
78 "type": "string"
79 },
80 "type": {
81 "type": "string",
82 "enum": [
83 "file",
84 "folder"
85 ]
86 },
87 "size": {
88 "type": "integer"
89 },
90 "mtime": {
91 "type": "string",
92 "format": "date-time"
93 },
94 "mtime_ms": {
95 "type": "integer"
96 },
97 "version": {
98 "type": "string",
99 "description": "Opaque version; also the ETag. Changes on every content change."
100 },
101 "sha256": {
102 "type": "string",
103 "nullable": true,
104 "description": "Hex SHA-256 when known (uploaded via API or requested with hash=1)"
105 }
106 }
107 },
108 "DeltaEntry": {
109 "type": "object",
110 "properties": {
111 "change": {
112 "type": "string",
113 "enum": [
114 "exists",
115 "created",
116 "modified",
117 "moved",
118 "deleted"
119 ]
120 },
121 "id": {
122 "type": "string"
123 },
124 "path": {
125 "type": "string"
126 },
127 "old_path": {
128 "type": "string",
129 "description": "Only for moved"
130 },
131 "type": {
132 "type": "string",
133 "enum": [
134 "file",
135 "folder"
136 ]
137 },
138 "size": {
139 "type": "integer",
140 "nullable": true
141 },
142 "mtime_ms": {
143 "type": "integer",
144 "nullable": true
145 },
146 "version": {
147 "type": "string",
148 "nullable": true
149 }
150 }
151 },
152 "Upload": {
153 "type": "object",
154 "properties": {
155 "id": {
156 "type": "string"
157 },
158 "path": {
159 "type": "string"
160 },
161 "size": {
162 "type": "integer"
163 },
164 "offset": {
165 "type": "integer"
166 },
167 "expires_at": {
168 "type": "string",
169 "format": "date-time"
170 },
171 "max_chunk_bytes": {
172 "type": "integer"
173 }
174 }
175 },
176 "Root": {
177 "type": "object",
178 "properties": {
179 "id": {
180 "type": "string",
181 "description": "'~' is the user's own folder"
182 },
183 "name": {
184 "type": "string"
185 },
186 "path": {
187 "type": "string"
188 },
189 "writable": {
190 "type": "boolean"
191 }
192 }
193 }
194 },
195 "responses": {
196 "Error": {
197 "description": "JSON error",
198 "content": {
199 "application/json": {
200 "schema": {
201 "$ref": "#/components/schemas/Error"
202 }
203 }
204 }
205 }
206 }
207 },
208 "paths": {
209 "/me": {
210 "get": {
211 "summary": "Current user, scopes, roots and limits",
212 "security": [
213 {
214 "oauth2": []
215 },
216 {
217 "personalToken": []
218 }
219 ],
220 "responses": {
221 "200": {
222 "description": "OK"
223 },
224 "401": {
225 "$ref": "#/components/responses/Error"
226 }
227 }
228 }
229 },
230 "/roots": {
231 "get": {
232 "summary": "Roots the user can read",
233 "security": [
234 {
235 "oauth2": [
236 "files:read"
237 ]
238 },
239 {
240 "personalToken": []
241 }
242 ],
243 "responses": {
244 "200": {
245 "description": "OK",
246 "content": {
247 "application/json": {
248 "schema": {
249 "type": "object",
250 "properties": {
251 "roots": {
252 "type": "array",
253 "items": {
254 "$ref": "#/components/schemas/Root"
255 }
256 }
257 }
258 }
259 }
260 }
261 },
262 "401": {
263 "$ref": "#/components/responses/Error"
264 }
265 }
266 }
267 },
268 "/files/metadata": {
269 "get": {
270 "summary": "Metadata of one file or folder",
271 "security": [
272 {
273 "oauth2": [
274 "files:read"
275 ]
276 },
277 {
278 "personalToken": []
279 }
280 ],
281 "parameters": [
282 {
283 "name": "path",
284 "in": "query",
285 "required": true,
286 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
287 "schema": {
288 "type": "string"
289 }
290 },
291 {
292 "name": "hash",
293 "in": "query",
294 "required": false,
295 "description": "1 = compute sha256 now if unknown (limited by api.maxHashBytes)",
296 "schema": {
297 "type": "string"
298 }
299 }
300 ],
301 "responses": {
302 "200": {
303 "description": "OK",
304 "content": {
305 "application/json": {
306 "schema": {
307 "$ref": "#/components/schemas/Entry"
308 }
309 }
310 }
311 },
312 "404": {
313 "$ref": "#/components/responses/Error"
314 }
315 }
316 }
317 },
318 "/files/list": {
319 "get": {
320 "summary": "List a folder (sorted by name, paged)",
321 "security": [
322 {
323 "oauth2": [
324 "files:read"
325 ]
326 },
327 {
328 "personalToken": []
329 }
330 ],
331 "parameters": [
332 {
333 "name": "path",
334 "in": "query",
335 "required": true,
336 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
337 "schema": {
338 "type": "string"
339 }
340 },
341 {
342 "name": "limit",
343 "in": "query",
344 "required": false,
345 "description": "1-1000, default 500",
346 "schema": {
347 "type": "integer"
348 }
349 },
350 {
351 "name": "page_token",
352 "in": "query",
353 "required": false,
354 "description": "From next_page_token",
355 "schema": {
356 "type": "string"
357 }
358 }
359 ],
360 "responses": {
361 "200": {
362 "description": "OK",
363 "content": {
364 "application/json": {
365 "schema": {
366 "type": "object",
367 "properties": {
368 "folder": {
369 "$ref": "#/components/schemas/Entry"
370 },
371 "entries": {
372 "type": "array",
373 "items": {
374 "$ref": "#/components/schemas/Entry"
375 }
376 },
377 "next_page_token": {
378 "type": "string",
379 "nullable": true
380 }
381 }
382 }
383 }
384 }
385 },
386 "404": {
387 "$ref": "#/components/responses/Error"
388 }
389 }
390 }
391 },
392 "/files/content": {
393 "get": {
394 "summary": "Download (supports Range, If-Range, If-None-Match)",
395 "security": [
396 {
397 "oauth2": [
398 "files:read"
399 ]
400 },
401 {
402 "personalToken": []
403 }
404 ],
405 "parameters": [
406 {
407 "name": "path",
408 "in": "query",
409 "required": true,
410 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
411 "schema": {
412 "type": "string"
413 }
414 },
415 {
416 "name": "Range",
417 "in": "header",
418 "required": false,
419 "description": "bytes=start-end",
420 "schema": {
421 "type": "string"
422 }
423 },
424 {
425 "name": "If-None-Match",
426 "in": "header",
427 "required": false,
428 "description": "Version/ETag",
429 "schema": {
430 "type": "string"
431 }
432 }
433 ],
434 "responses": {
435 "200": {
436 "description": "File bytes"
437 },
438 "206": {
439 "description": "Partial content"
440 },
441 "304": {
442 "description": "Not modified"
443 },
444 "404": {
445 "$ref": "#/components/responses/Error"
446 }
447 }
448 },
449 "put": {
450 "summary": "Upload a whole file in one request (small/medium files)",
451 "security": [
452 {
453 "oauth2": [
454 "files:write"
455 ]
456 },
457 {
458 "personalToken": []
459 }
460 ],
461 "parameters": [
462 {
463 "name": "path",
464 "in": "query",
465 "required": true,
466 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
467 "schema": {
468 "type": "string"
469 }
470 },
471 {
472 "name": "mtime",
473 "in": "query",
474 "required": false,
475 "description": "Epoch ms or ISO date to set as modification time",
476 "schema": {
477 "type": "string"
478 }
479 },
480 {
481 "name": "overwrite",
482 "in": "query",
483 "required": false,
484 "description": "true = replace without If-Match",
485 "schema": {
486 "type": "string"
487 }
488 },
489 {
490 "name": "If-Match",
491 "in": "header",
492 "required": false,
493 "description": "Replace only if current version matches",
494 "schema": {
495 "type": "string"
496 }
497 },
498 {
499 "name": "If-None-Match",
500 "in": "header",
501 "required": false,
502 "description": "* = create only",
503 "schema": {
504 "type": "string"
505 }
506 },
507 {
508 "name": "X-Content-SHA256",
509 "in": "header",
510 "required": false,
511 "description": "Hex SHA-256; verified before the file becomes visible",
512 "schema": {
513 "type": "string"
514 }
515 }
516 ],
517 "requestBody": {
518 "content": {
519 "application/octet-stream": {
520 "schema": {
521 "type": "string",
522 "format": "binary"
523 }
524 }
525 }
526 },
527 "responses": {
528 "200": {
529 "description": "Replaced",
530 "content": {
531 "application/json": {
532 "schema": {
533 "$ref": "#/components/schemas/Entry"
534 }
535 }
536 }
537 },
538 "201": {
539 "description": "Created",
540 "content": {
541 "application/json": {
542 "schema": {
543 "$ref": "#/components/schemas/Entry"
544 }
545 }
546 }
547 },
548 "403": {
549 "$ref": "#/components/responses/Error"
550 },
551 "409": {
552 "$ref": "#/components/responses/Error"
553 },
554 "412": {
555 "$ref": "#/components/responses/Error"
556 },
557 "413": {
558 "$ref": "#/components/responses/Error"
559 },
560 "422": {
561 "$ref": "#/components/responses/Error"
562 },
563 "507": {
564 "$ref": "#/components/responses/Error"
565 }
566 }
567 }
568 },
569 "/folders": {
570 "post": {
571 "summary": "Create a folder",
572 "security": [
573 {
574 "oauth2": [
575 "files:write"
576 ]
577 },
578 {
579 "personalToken": []
580 }
581 ],
582 "requestBody": {
583 "content": {
584 "application/json": {
585 "schema": {
586 "type": "object",
587 "required": [
588 "path"
589 ],
590 "properties": {
591 "path": {
592 "type": "string"
593 },
594 "parents": {
595 "type": "boolean"
596 },
597 "exist_ok": {
598 "type": "boolean"
599 }
600 }
601 }
602 }
603 }
604 },
605 "responses": {
606 "201": {
607 "description": "Created",
608 "content": {
609 "application/json": {
610 "schema": {
611 "$ref": "#/components/schemas/Entry"
612 }
613 }
614 }
615 },
616 "200": {
617 "description": "Already existed (exist_ok)",
618 "content": {
619 "application/json": {
620 "schema": {
621 "$ref": "#/components/schemas/Entry"
622 }
623 }
624 }
625 },
626 "409": {
627 "$ref": "#/components/responses/Error"
628 }
629 }
630 }
631 },
632 "/files/move": {
633 "post": {
634 "summary": "Rename or move (also between roots)",
635 "security": [
636 {
637 "oauth2": [
638 "files:write"
639 ]
640 },
641 {
642 "personalToken": []
643 }
644 ],
645 "requestBody": {
646 "content": {
647 "application/json": {
648 "schema": {
649 "type": "object",
650 "required": [
651 "from",
652 "to"
653 ],
654 "properties": {
655 "from": {
656 "type": "string"
657 },
658 "to": {
659 "type": "string"
660 },
661 "if_match": {
662 "type": "string"
663 },
664 "overwrite": {
665 "type": "boolean",
666 "description": "Replace an existing file at 'to' (never folders)"
667 }
668 }
669 }
670 }
671 }
672 },
673 "responses": {
674 "200": {
675 "description": "Moved",
676 "content": {
677 "application/json": {
678 "schema": {
679 "$ref": "#/components/schemas/Entry"
680 }
681 }
682 }
683 },
684 "409": {
685 "$ref": "#/components/responses/Error"
686 },
687 "412": {
688 "$ref": "#/components/responses/Error"
689 }
690 }
691 }
692 },
693 "/files": {
694 "delete": {
695 "summary": "Delete permanently (there is no trash)",
696 "security": [
697 {
698 "oauth2": [
699 "files:write"
700 ]
701 },
702 {
703 "personalToken": []
704 }
705 ],
706 "parameters": [
707 {
708 "name": "path",
709 "in": "query",
710 "required": true,
711 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
712 "schema": {
713 "type": "string"
714 }
715 },
716 {
717 "name": "recursive",
718 "in": "query",
719 "required": false,
720 "description": "true to delete a non-empty folder",
721 "schema": {
722 "type": "string"
723 }
724 },
725 {
726 "name": "If-Match",
727 "in": "header",
728 "required": false,
729 "description": "Only delete this version",
730 "schema": {
731 "type": "string"
732 }
733 }
734 ],
735 "responses": {
736 "204": {
737 "description": "Deleted"
738 },
739 "409": {
740 "$ref": "#/components/responses/Error"
741 },
742 "412": {
743 "$ref": "#/components/responses/Error"
744 }
745 }
746 }
747 },
748 "/delta": {
749 "get": {
750 "summary": "Change feed per root",
751 "description": "Without cursor: full snapshot (change=exists, reset=true), paged. Then pass the returned cursor to get created/modified/moved/deleted changes. Children of moved or deleted folders are implied. 410 means start over without a cursor.",
752 "security": [
753 {
754 "oauth2": [
755 "files:read"
756 ]
757 },
758 {
759 "personalToken": []
760 }
761 ],
762 "parameters": [
763 {
764 "name": "root",
765 "in": "query",
766 "required": false,
767 "description": "Root id (from /roots)",
768 "schema": {
769 "type": "string"
770 }
771 },
772 {
773 "name": "cursor",
774 "in": "query",
775 "required": false,
776 "description": "From the previous response",
777 "schema": {
778 "type": "string"
779 }
780 },
781 {
782 "name": "limit",
783 "in": "query",
784 "required": false,
785 "description": "1-1000, default 500",
786 "schema": {
787 "type": "integer"
788 }
789 }
790 ],
791 "responses": {
792 "200": {
793 "description": "OK",
794 "content": {
795 "application/json": {
796 "schema": {
797 "type": "object",
798 "properties": {
799 "reset": {
800 "type": "boolean"
801 },
802 "entries": {
803 "type": "array",
804 "items": {
805 "$ref": "#/components/schemas/DeltaEntry"
806 }
807 },
808 "cursor": {
809 "type": "string"
810 },
811 "has_more": {
812 "type": "boolean"
813 }
814 }
815 }
816 }
817 }
818 },
819 "400": {
820 "$ref": "#/components/responses/Error"
821 },
822 "410": {
823 "$ref": "#/components/responses/Error"
824 }
825 }
826 }
827 },
828 "/uploads": {
829 "post": {
830 "summary": "Start a resumable upload",
831 "security": [
832 {
833 "oauth2": [
834 "files:write"
835 ]
836 },
837 {
838 "personalToken": []
839 }
840 ],
841 "requestBody": {
842 "content": {
843 "application/json": {
844 "schema": {
845 "type": "object",
846 "required": [
847 "path",
848 "size"
849 ],
850 "properties": {
851 "path": {
852 "type": "string"
853 },
854 "size": {
855 "type": "integer"
856 },
857 "sha256": {
858 "type": "string"
859 },
860 "mtime": {
861 "type": "integer"
862 },
863 "if_match": {
864 "type": "string"
865 },
866 "if_none_match": {
867 "type": "string",
868 "enum": [
869 "*"
870 ]
871 },
872 "overwrite": {
873 "type": "boolean"
874 }
875 }
876 }
877 }
878 }
879 },
880 "responses": {
881 "201": {
882 "description": "Created",
883 "content": {
884 "application/json": {
885 "schema": {
886 "$ref": "#/components/schemas/Upload"
887 }
888 }
889 }
890 },
891 "409": {
892 "$ref": "#/components/responses/Error"
893 },
894 "412": {
895 "$ref": "#/components/responses/Error"
896 },
897 "413": {
898 "$ref": "#/components/responses/Error"
899 },
900 "429": {
901 "$ref": "#/components/responses/Error"
902 },
903 "507": {
904 "$ref": "#/components/responses/Error"
905 }
906 }
907 }
908 },
909 "/uploads/{id}": {
910 "parameters": [
911 {
912 "name": "id",
913 "in": "path",
914 "required": true,
915 "description": "Upload id",
916 "schema": {
917 "type": "string"
918 }
919 }
920 ],
921 "get": {
922 "summary": "Upload status (offset to resume from)",
923 "security": [
924 {
925 "oauth2": [
926 "files:write"
927 ]
928 },
929 {
930 "personalToken": []
931 }
932 ],
933 "responses": {
934 "200": {
935 "description": "OK",
936 "content": {
937 "application/json": {
938 "schema": {
939 "$ref": "#/components/schemas/Upload"
940 }
941 }
942 }
943 },
944 "404": {
945 "$ref": "#/components/responses/Error"
946 }
947 }
948 },
949 "patch": {
950 "summary": "Append a chunk at Upload-Offset",
951 "security": [
952 {
953 "oauth2": [
954 "files:write"
955 ]
956 },
957 {
958 "personalToken": []
959 }
960 ],
961 "parameters": [
962 {
963 "name": "Upload-Offset",
964 "in": "header",
965 "required": true,
966 "description": "Must equal the current offset",
967 "schema": {
968 "type": "integer"
969 }
970 }
971 ],
972 "requestBody": {
973 "content": {
974 "application/octet-stream": {
975 "schema": {
976 "type": "string",
977 "format": "binary"
978 }
979 }
980 }
981 },
982 "responses": {
983 "200": {
984 "description": "OK",
985 "content": {
986 "application/json": {
987 "schema": {
988 "$ref": "#/components/schemas/Upload"
989 }
990 }
991 }
992 },
993 "409": {
994 "$ref": "#/components/responses/Error"
995 },
996 "413": {
997 "$ref": "#/components/responses/Error"
998 }
999 }
1000 },
1001 "delete": {
1002 "summary": "Cancel",
1003 "security": [
1004 {
1005 "oauth2": [
1006 "files:write"
1007 ]
1008 },
1009 {
1010 "personalToken": []
1011 }
1012 ],
1013 "responses": {
1014 "204": {
1015 "description": "Cancelled"
1016 }
1017 }
1018 }
1019 },
1020 "/uploads/{id}/complete": {
1021 "parameters": [
1022 {
1023 "name": "id",
1024 "in": "path",
1025 "required": true,
1026 "description": "Upload id",
1027 "schema": {
1028 "type": "string"
1029 }
1030 }
1031 ],
1032 "post": {
1033 "summary": "Verify size/sha256 and atomically place the file",
1034 "security": [
1035 {
1036 "oauth2": [
1037 "files:write"
1038 ]
1039 },
1040 {
1041 "personalToken": []
1042 }
1043 ],
1044 "responses": {
1045 "200": {
1046 "description": "Replaced",
1047 "content": {
1048 "application/json": {
1049 "schema": {
1050 "$ref": "#/components/schemas/Entry"
1051 }
1052 }
1053 }
1054 },
1055 "201": {
1056 "description": "Created",
1057 "content": {
1058 "application/json": {
1059 "schema": {
1060 "$ref": "#/components/schemas/Entry"
1061 }
1062 }
1063 }
1064 },
1065 "409": {
1066 "$ref": "#/components/responses/Error"
1067 },
1068 "412": {
1069 "$ref": "#/components/responses/Error"
1070 },
1071 "422": {
1072 "$ref": "#/components/responses/Error"
1073 }
1074 }
1075 }
1076 }
1077 }
1078}