aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc
diff options
context:
space:
mode:
Diffstat (limited to 'support/doc')
-rw-r--r--support/doc/api/openapi.yaml295
1 files changed, 245 insertions, 50 deletions
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 666e48a41..af829cc62 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -10,27 +10,41 @@ info:
10 url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE' 10 url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE'
11 x-logo: 11 x-logo:
12 url: 'https://joinpeertube.org/img/brand.png' 12 url: 'https://joinpeertube.org/img/brand.png'
13 altText: PeerTube Project Homepage
13 description: | 14 description: |
14 # Introduction 15 # Introduction
15 The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable 16 The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable
16 resource URLs. It returns HTTP response codes to indicate errors. It also 17 resource URLs. It returns HTTP response codes to indicate errors. It also
17 accepts and returns JSON in the HTTP body. You can use your favorite 18 accepts and returns JSON in the HTTP body. You can use your favorite
18 HTTP/REST library for your programming language to use PeerTube. No official 19 HTTP/REST library for your programming language to use PeerTube. No official
19 SDK is currently provided. 20 SDK is currently provided, but the spec API is fully compatible with
21 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
22 which generates a client SDK in the language of your choice.
20 23
21 # Authentication 24 # Authentication
22 When you sign up for an account, you are given the possibility to generate 25 When you sign up for an account, you are given the possibility to generate
23 sessions, and authenticate using this session token. One session token can 26 sessions, and authenticate using this session token. One session token can
24 currently be used at a time. 27 currently be used at a time.
28
29 # Errors
30 The API uses standard HTTP status codes to indicate the success or failure
31 of the API call. The body of the response will be JSON in the following
32 format.
33
34 ```
35 {
36 "code": "unauthorized_request", // example inner error code
37 "error": "Token is invalid." // example exposed error message
38 }
39 ```
40externalDocs:
41 url: https://docs.joinpeertube.org/api.html
25tags: 42tags:
26 - name: Accounts 43 - name: Accounts
27 description: > 44 description: >
28 Using some features of PeerTube require authentication, for which Accounts 45 Using some features of PeerTube require authentication, for which Accounts
29
30 provide different levels of permission as well as associated user 46 provide different levels of permission as well as associated user
31 information. 47 information. Accounts also encompass remote accounts discovered across the federation.
32
33 Accounts also encompass remote accounts discovered across the federation.
34 - name: Config 48 - name: Config
35 description: > 49 description: >
36 Each server exposes public information regarding supported videos and 50 Each server exposes public information regarding supported videos and
@@ -42,23 +56,15 @@ tags:
42 - name: Job 56 - name: Job
43 description: > 57 description: >
44 Jobs are long-running tasks enqueued and processed by the instance 58 Jobs are long-running tasks enqueued and processed by the instance
45 itself. 59 itself. No additional worker registration is currently available.
46 60 - name: Server Following
47 No additional worker registration is currently available.
48 - name: ServerFollowing
49 description: > 61 description: >
50 Managing servers which the instance interacts with is crucial to the 62 Managing servers which the instance interacts with is crucial to the
51 concept 63 concept of federation in PeerTube and external video indexation. The PeerTube
52 64 server then deals with inter-server ActivityPub operations and propagates
53 of federation in PeerTube and external video indexation. The PeerTube
54 server
55
56 then deals with inter-server ActivityPub operations and propagates
57
58 information across its social graph by posting activities to actors' inbox 65 information across its social graph by posting activities to actors' inbox
59
60 endpoints. 66 endpoints.
61 - name: VideoAbuse 67 - name: Video Abuse
62 description: | 68 description: |
63 Video abuses deal with reports of local or remote videos alike. 69 Video abuses deal with reports of local or remote videos alike.
64 - name: Video 70 - name: Video
@@ -70,16 +76,51 @@ tags:
70 Videos from other instances federated by the instance (that is, instances 76 Videos from other instances federated by the instance (that is, instances
71 followed by the instance) can be found via keywords and other criteria of 77 followed by the instance) can be found via keywords and other criteria of
72 the advanced search. 78 the advanced search.
73 - name: VideoComment 79 - name: Video Comment
74 description: > 80 description: >
75 Operations dealing with comments to a video. Comments are organized in 81 Operations dealing with comments to a video. Comments are organized in
76 threads. 82 threads.
77 - name: VideoChannel 83 - name: Video Channel
78 description: > 84 description: >
79 Operations dealing with creation, modification and video listing of a 85 Operations dealing with creation, modification and video listing of a
80 user's 86 user's channels.
81 87 - name: Video Blacklist
82 channels. 88 description: >
89 Operations dealing with blacklisting videos (removing them from view and
90 preventing interactions).
91 - name: Video Rate
92 description: >
93 Voting for a video.
94x-tagGroups:
95 - name: Accounts
96 tags:
97 - Accounts
98 - User
99 - name: Videos
100 tags:
101 - Video
102 - Video Channel
103 - Video Comment
104 - Video Abuse
105 - Video Following
106 - Video Rate
107 - name: Moderation
108 tags:
109 - Video Abuse
110 - Video Blacklist
111 - name: Public Instance Information
112 tags:
113 - Config
114 - Server Following
115 - name: Notifications
116 tags:
117 - Feeds
118 - name: Jobs
119 tags:
120 - Job
121 - name: Search
122 tags:
123 - Search
83paths: 124paths:
84 '/accounts/{name}': 125 '/accounts/{name}':
85 get: 126 get:
@@ -126,6 +167,37 @@ paths:
126 source: | 167 source: |
127 # pip install httpie 168 # pip install httpie
128 http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos 169 http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
170 - lang: Ruby
171 source: |
172 require 'uri'
173 require 'net/http'
174
175 url = URI("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
176
177 http = Net::HTTP.new(url.host, url.port)
178 http.use_ssl = true
179 http.verify_mode = OpenSSL::SSL::VERIFY_NONE
180
181 request = Net::HTTP::Post.new(url)
182 request["content-type"] = 'application/json'
183 response = http.request(request)
184 puts response.read_body
185 - lang: Python
186 source: |
187 import http.client
188
189 conn = http.client.HTTPSConnection("https://peertube2.cpy.re/api/v1")
190
191 headers = {
192 'content-type': "application/json"
193 }
194
195 conn.request("POST", "/accounts/{name}/videos", None, headers)
196
197 res = conn.getresponse()
198 data = res.read()
199
200 print(data.decode("utf-8"))
129 /accounts: 201 /accounts:
130 get: 202 get:
131 tags: 203 tags:
@@ -144,7 +216,7 @@ paths:
144 get: 216 get:
145 tags: 217 tags:
146 - Config 218 - Config
147 summary: Get the configuration of the server 219 summary: Get the public configuration of the server
148 responses: 220 responses:
149 '200': 221 '200':
150 description: successful operation 222 description: successful operation
@@ -152,6 +224,45 @@ paths:
152 application/json: 224 application/json:
153 schema: 225 schema:
154 $ref: '#/components/schemas/ServerConfig' 226 $ref: '#/components/schemas/ServerConfig'
227 /config/about:
228 get:
229 summary: Get the instance about page content
230 tags:
231 - Config
232 responses:
233 '200':
234 description: successful operation
235 /config/custom:
236 get:
237 summary: Get the runtime configuration of the server
238 tags:
239 - Config
240 security:
241 - OAuth2:
242 - admin
243 responses:
244 '200':
245 description: successful operation
246 put:
247 summary: Set the runtime configuration of the server
248 tags:
249 - Config
250 security:
251 - OAuth2:
252 - admin
253 responses:
254 '200':
255 description: successful operation
256 delete:
257 summary: Delete the runtime configuration of the server
258 tags:
259 - Config
260 security:
261 - OAuth2:
262 - admin
263 responses:
264 '200':
265 description: successful operation
155 '/feeds/videos.{format}': 266 '/feeds/videos.{format}':
156 get: 267 get:
157 summary: >- 268 summary: >-
@@ -223,7 +334,7 @@ paths:
223 - OAuth2: 334 - OAuth2:
224 - admin 335 - admin
225 tags: 336 tags:
226 - ServerFollowing 337 - Server Following
227 summary: Unfollow a server by hostname 338 summary: Unfollow a server by hostname
228 parameters: 339 parameters:
229 - name: host 340 - name: host
@@ -238,7 +349,7 @@ paths:
238 /server/followers: 349 /server/followers:
239 get: 350 get:
240 tags: 351 tags:
241 - ServerFollowing 352 - Server Following
242 summary: Get followers of the server 353 summary: Get followers of the server
243 parameters: 354 parameters:
244 - $ref: '#/components/parameters/start' 355 - $ref: '#/components/parameters/start'
@@ -256,7 +367,7 @@ paths:
256 /server/following: 367 /server/following:
257 get: 368 get:
258 tags: 369 tags:
259 - ServerFollowing 370 - Server Following
260 summary: Get servers followed by the server 371 summary: Get servers followed by the server
261 parameters: 372 parameters:
262 - $ref: '#/components/parameters/start' 373 - $ref: '#/components/parameters/start'
@@ -276,7 +387,7 @@ paths:
276 - OAuth2: 387 - OAuth2:
277 - admin 388 - admin
278 tags: 389 tags:
279 - ServerFollowing 390 - Server Following
280 summary: Follow a server 391 summary: Follow a server
281 responses: 392 responses:
282 '204': 393 '204':
@@ -701,6 +812,85 @@ paths:
701 responses: 812 responses:
702 '204': 813 '204':
703 $ref: '#/paths/~1users~1me/put/responses/204' 814 $ref: '#/paths/~1users~1me/put/responses/204'
815 '/videos/{id}/watching':
816 put:
817 summary: Indicate progress of in watching the video by its id for a user
818 tags:
819 - Video
820 security:
821 - OAuth2: []
822 parameters:
823 - $ref: '#/components/parameters/id2'
824 requestBody:
825 content:
826 application/json:
827 schema:
828 $ref: '#/components/schemas/UserWatchingVideo'
829 required: true
830 responses:
831 '204':
832 $ref: '#/paths/~1users~1me/put/responses/204'
833 /videos/ownership:
834 get:
835 summary: Get list of video ownership changes requests
836 tags:
837 - Video
838 security:
839 - OAuth2: []
840 parameters:
841 - $ref: '#/components/parameters/id2'
842 responses:
843 '200':
844 description: successful operation
845 '/videos/ownership/{id}/accept':
846 post:
847 summary: Refuse ownership change request for video by its id
848 tags:
849 - Video
850 security:
851 - OAuth2: []
852 parameters:
853 - $ref: '#/components/parameters/id2'
854 responses:
855 '204':
856 $ref: '#/paths/~1users~1me/put/responses/204'
857 '/videos/ownership/{id}/refuse':
858 post:
859 summary: Accept ownership change request for video by its id
860 tags:
861 - Video
862 security:
863 - OAuth2: []
864 parameters:
865 - $ref: '#/components/parameters/id2'
866 responses:
867 '204':
868 $ref: '#/paths/~1users~1me/put/responses/204'
869 '/videos/{id}/give-ownership':
870 post:
871 summary: Request change of ownership for a video you own, by its id
872 tags:
873 - Video
874 security:
875 - OAuth2: []
876 parameters:
877 - $ref: '#/components/parameters/id2'
878 requestBody:
879 required: true
880 content:
881 application/x-www-form-urlencoded:
882 schema:
883 type: object
884 properties:
885 username:
886 type: string
887 required:
888 - username
889 responses:
890 '204':
891 $ref: '#/paths/~1users~1me/put/responses/204'
892 '400':
893 description: 'Changing video ownership to a remote account is not supported yet'
704 /videos/upload: 894 /videos/upload:
705 post: 895 post:
706 summary: Upload a video file with its metadata 896 summary: Upload a video file with its metadata
@@ -771,7 +961,6 @@ paths:
771 - videofile 961 - videofile
772 - channelId 962 - channelId
773 - name 963 - name
774 - privacy
775 x-code-samples: 964 x-code-samples:
776 - lang: Shell 965 - lang: Shell
777 source: | 966 source: |
@@ -781,7 +970,6 @@ paths:
781 PASSWORD="<your_password>" 970 PASSWORD="<your_password>"
782 FILE_PATH="<your_file_path>" 971 FILE_PATH="<your_file_path>"
783 CHANNEL_ID="<your_channel_id>" 972 CHANNEL_ID="<your_channel_id>"
784 PRIVACY="1" # public: 1, unlisted: 2, private: 3
785 NAME="<video_name>" 973 NAME="<video_name>"
786 974
787 API_PATH="https://peertube2.cpy.re/api/v1" 975 API_PATH="https://peertube2.cpy.re/api/v1"
@@ -798,7 +986,6 @@ paths:
798 videofile@$FILE_PATH \ 986 videofile@$FILE_PATH \
799 channelId=$CHANNEL_ID \ 987 channelId=$CHANNEL_ID \
800 name=$NAME \ 988 name=$NAME \
801 privacy=$PRIVACY \
802 "Authorization:Bearer $token" 989 "Authorization:Bearer $token"
803 /videos/abuse: 990 /videos/abuse:
804 get: 991 get:
@@ -806,7 +993,7 @@ paths:
806 security: 993 security:
807 - OAuth2: [] 994 - OAuth2: []
808 tags: 995 tags:
809 - VideoAbuse 996 - Video Abuse
810 parameters: 997 parameters:
811 - $ref: '#/components/parameters/start' 998 - $ref: '#/components/parameters/start'
812 - $ref: '#/components/parameters/count' 999 - $ref: '#/components/parameters/count'
@@ -826,7 +1013,7 @@ paths:
826 security: 1013 security:
827 - OAuth2: [] 1014 - OAuth2: []
828 tags: 1015 tags:
829 - VideoAbuse 1016 - Video Abuse
830 parameters: 1017 parameters:
831 - $ref: '#/components/parameters/id2' 1018 - $ref: '#/components/parameters/id2'
832 responses: 1019 responses:
@@ -840,7 +1027,7 @@ paths:
840 - admin 1027 - admin
841 - moderator 1028 - moderator
842 tags: 1029 tags:
843 - VideoBlacklist 1030 - Video Blacklist
844 parameters: 1031 parameters:
845 - $ref: '#/components/parameters/id2' 1032 - $ref: '#/components/parameters/id2'
846 responses: 1033 responses:
@@ -853,7 +1040,7 @@ paths:
853 - admin 1040 - admin
854 - moderator 1041 - moderator
855 tags: 1042 tags:
856 - VideoBlacklist 1043 - Video Blacklist
857 parameters: 1044 parameters:
858 - $ref: '#/components/parameters/id2' 1045 - $ref: '#/components/parameters/id2'
859 responses: 1046 responses:
@@ -867,7 +1054,7 @@ paths:
867 - admin 1054 - admin
868 - moderator 1055 - moderator
869 tags: 1056 tags:
870 - VideoBlacklist 1057 - Video Blacklist
871 parameters: 1058 parameters:
872 - $ref: '#/components/parameters/start' 1059 - $ref: '#/components/parameters/start'
873 - $ref: '#/components/parameters/count' 1060 - $ref: '#/components/parameters/count'
@@ -885,7 +1072,7 @@ paths:
885 get: 1072 get:
886 summary: Get list of video channels 1073 summary: Get list of video channels
887 tags: 1074 tags:
888 - VideoChannel 1075 - Video Channel
889 parameters: 1076 parameters:
890 - $ref: '#/components/parameters/start' 1077 - $ref: '#/components/parameters/start'
891 - $ref: '#/components/parameters/count' 1078 - $ref: '#/components/parameters/count'
@@ -904,7 +1091,7 @@ paths:
904 security: 1091 security:
905 - OAuth2: [] 1092 - OAuth2: []
906 tags: 1093 tags:
907 - VideoChannel 1094 - Video Channel
908 responses: 1095 responses:
909 '204': 1096 '204':
910 $ref: '#/paths/~1users~1me/put/responses/204' 1097 $ref: '#/paths/~1users~1me/put/responses/204'
@@ -914,7 +1101,7 @@ paths:
914 get: 1101 get:
915 summary: Get a video channel by its id 1102 summary: Get a video channel by its id
916 tags: 1103 tags:
917 - VideoChannel 1104 - Video Channel
918 parameters: 1105 parameters:
919 - $ref: '#/components/parameters/id3' 1106 - $ref: '#/components/parameters/id3'
920 responses: 1107 responses:
@@ -929,7 +1116,7 @@ paths:
929 security: 1116 security:
930 - OAuth2: [] 1117 - OAuth2: []
931 tags: 1118 tags:
932 - VideoChannel 1119 - Video Channel
933 parameters: 1120 parameters:
934 - $ref: '#/components/parameters/id3' 1121 - $ref: '#/components/parameters/id3'
935 responses: 1122 responses:
@@ -942,7 +1129,7 @@ paths:
942 security: 1129 security:
943 - OAuth2: [] 1130 - OAuth2: []
944 tags: 1131 tags:
945 - VideoChannel 1132 - Video Channel
946 parameters: 1133 parameters:
947 - $ref: '#/components/parameters/id3' 1134 - $ref: '#/components/parameters/id3'
948 responses: 1135 responses:
@@ -952,7 +1139,7 @@ paths:
952 get: 1139 get:
953 summary: Get videos of a video channel by its id 1140 summary: Get videos of a video channel by its id
954 tags: 1141 tags:
955 - VideoChannel 1142 - Video Channel
956 parameters: 1143 parameters:
957 - $ref: '#/components/parameters/id3' 1144 - $ref: '#/components/parameters/id3'
958 responses: 1145 responses:
@@ -966,7 +1153,7 @@ paths:
966 get: 1153 get:
967 summary: Get video channels of an account by its name 1154 summary: Get video channels of an account by its name
968 tags: 1155 tags:
969 - VideoChannel 1156 - Video Channel
970 parameters: 1157 parameters:
971 - $ref: '#/components/parameters/name' 1158 - $ref: '#/components/parameters/name'
972 responses: 1159 responses:
@@ -982,7 +1169,7 @@ paths:
982 get: 1169 get:
983 summary: Get the comment threads of a video by its id 1170 summary: Get the comment threads of a video by its id
984 tags: 1171 tags:
985 - VideoComment 1172 - Video Comment
986 parameters: 1173 parameters:
987 - $ref: '#/components/parameters/id2' 1174 - $ref: '#/components/parameters/id2'
988 - $ref: '#/components/parameters/start' 1175 - $ref: '#/components/parameters/start'
@@ -1000,7 +1187,7 @@ paths:
1000 security: 1187 security:
1001 - OAuth2: [] 1188 - OAuth2: []
1002 tags: 1189 tags:
1003 - VideoComment 1190 - Video Comment
1004 parameters: 1191 parameters:
1005 - $ref: '#/components/parameters/id2' 1192 - $ref: '#/components/parameters/id2'
1006 responses: 1193 responses:
@@ -1014,7 +1201,7 @@ paths:
1014 get: 1201 get:
1015 summary: 'Get the comment thread by its id, of a video by its id' 1202 summary: 'Get the comment thread by its id, of a video by its id'
1016 tags: 1203 tags:
1017 - VideoComment 1204 - Video Comment
1018 parameters: 1205 parameters:
1019 - $ref: '#/components/parameters/id2' 1206 - $ref: '#/components/parameters/id2'
1020 - name: threadId 1207 - name: threadId
@@ -1036,7 +1223,7 @@ paths:
1036 security: 1223 security:
1037 - OAuth2: [] 1224 - OAuth2: []
1038 tags: 1225 tags:
1039 - VideoComment 1226 - Video Comment
1040 parameters: 1227 parameters:
1041 - $ref: '#/components/parameters/id2' 1228 - $ref: '#/components/parameters/id2'
1042 - $ref: '#/components/parameters/commentId' 1229 - $ref: '#/components/parameters/commentId'
@@ -1052,7 +1239,7 @@ paths:
1052 security: 1239 security:
1053 - OAuth2: [] 1240 - OAuth2: []
1054 tags: 1241 tags:
1055 - VideoComment 1242 - Video Comment
1056 parameters: 1243 parameters:
1057 - $ref: '#/components/parameters/id2' 1244 - $ref: '#/components/parameters/id2'
1058 - $ref: '#/components/parameters/commentId' 1245 - $ref: '#/components/parameters/commentId'
@@ -1065,7 +1252,7 @@ paths:
1065 security: 1252 security:
1066 - OAuth2: [] 1253 - OAuth2: []
1067 tags: 1254 tags:
1068 - VideoRate 1255 - Video Rate
1069 parameters: 1256 parameters:
1070 - $ref: '#/components/parameters/id2' 1257 - $ref: '#/components/parameters/id2'
1071 responses: 1258 responses:
@@ -1096,8 +1283,12 @@ paths:
1096 items: 1283 items:
1097 $ref: '#/components/schemas/Video' 1284 $ref: '#/components/schemas/Video'
1098servers: 1285servers:
1286 - url: 'https://peertube.cpy.re/api/v1'
1287 description: Live Test Server (live data - stable version)
1099 - url: 'https://peertube2.cpy.re/api/v1' 1288 - url: 'https://peertube2.cpy.re/api/v1'
1100 description: Live Server 1289 description: Live Test Server (live data - bleeding edge version)
1290 - url: 'https://peertube3.cpy.re/api/v1'
1291 description: Live Test Server (live data - bleeding edge version)
1101components: 1292components:
1102 parameters: 1293 parameters:
1103 start: 1294 start:
@@ -1417,6 +1608,10 @@ components:
1417 type: array 1608 type: array
1418 items: 1609 items:
1419 $ref: '#/components/schemas/VideoChannel' 1610 $ref: '#/components/schemas/VideoChannel'
1611 UserWatchingVideo:
1612 properties:
1613 currentTime:
1614 type: number
1420 ServerConfig: 1615 ServerConfig:
1421 properties: 1616 properties:
1422 signup: 1617 signup: