ARI: Add the ability to download the media associated with a stored recording
[asterisk/asterisk.git] / rest-api / api-docs / recordings.json
1 {
2         "_copyright": "Copyright (C) 2012 - 2013, Digium, Inc.",
3         "_author": "David M. Lee, II <dlee@digium.com>",
4         "_svn_revision": "$Revision$",
5         "apiVersion": "1.7.0",
6         "swaggerVersion": "1.1",
7         "basePath": "http://localhost:8088/ari",
8         "resourcePath": "/api-docs/recordings.{format}",
9         "apis": [
10                 {
11                         "path": "/recordings/stored",
12                         "description": "Recordings",
13                         "operations": [
14                                 {
15                                         "httpMethod": "GET",
16                                         "summary": "List recordings that are complete.",
17                                         "nickname": "listStored",
18                                         "responseClass": "List[StoredRecording]"
19                                 }
20                         ]
21                 },
22                 {
23                         "path": "/recordings/stored/{recordingName}",
24                         "description": "Individual recording",
25                         "operations": [
26                                 {
27                                         "httpMethod": "GET",
28                                         "summary": "Get a stored recording's details.",
29                                         "nickname": "getStored",
30                                         "responseClass": "StoredRecording",
31                                         "parameters": [
32                                                 {
33                                                         "name": "recordingName",
34                                                         "description": "The name of the recording",
35                                                         "paramType": "path",
36                                                         "required": true,
37                                                         "allowMultiple": false,
38                                                         "dataType": "string"
39                                                 }
40                                         ],
41                                         "errorResponses": [
42                                                 {
43                                                         "code": 404,
44                                                         "reason": "Recording not found"
45                                                 }
46                                         ]
47                                 },
48                                 {
49                                         "httpMethod": "DELETE",
50                                         "summary": "Delete a stored recording.",
51                                         "nickname": "deleteStored",
52                                         "responseClass": "void",
53                                         "parameters": [
54                                                 {
55                                                         "name": "recordingName",
56                                                         "description": "The name of the recording",
57                                                         "paramType": "path",
58                                                         "required": true,
59                                                         "allowMultiple": false,
60                                                         "dataType": "string"
61                                                 }
62                                         ],
63                                         "errorResponses": [
64                                                 {
65                                                         "code": 404,
66                                                         "reason": "Recording not found"
67                                                 }
68                                         ]
69                                 }
70                         ]
71                 },
72                 {
73                         "path": "/recordings/stored/{recordingName}/file",
74                         "description": "The actual file associated with the stored recording",
75                         "operations": [
76                                 {
77                                         "httpMethod": "GET",
78                                         "summary": "Get the file associated with the stored recording.",
79                                         "nickname": "getStoredFile",
80                                         "responseClass": "binary",
81                                         "parameters": [
82                                                 {
83                                                         "name": "recordingName",
84                                                         "description": "The name of the recording",
85                                                         "paramType": "path",
86                                                         "required": true,
87                                                         "allowMultiple": false,
88                                                         "dataType": "string"
89                                                 }
90                                         ],
91                                         "errorResponses": [
92                                                 {
93                                                         "code": 403,
94                                                         "reason": "The recording file could not be opened"
95                                                 },
96                                                 {
97                                                         "code": 404,
98                                                         "reason": "Recording not found"
99                                                 }
100                                         ]
101                                 }
102                         ]
103                 },
104                 {
105                         "path": "/recordings/stored/{recordingName}/copy",
106                         "description": "Copy an individual recording",
107                         "operations": [
108                                 {
109                                         "httpMethod": "POST",
110                                         "summary": "Copy a stored recording.",
111                                         "nickname": "copyStored",
112                                         "responseClass": "StoredRecording",
113                                         "parameters": [
114                                                 {
115                                                         "name": "recordingName",
116                                                         "description": "The name of the recording to copy",
117                                                         "paramType": "path",
118                                                         "required": true,
119                                                         "allowMultiple": false,
120                                                         "dataType": "string"
121                                                 },
122                                                 {
123                                                         "name": "destinationRecordingName",
124                                                         "description": "The destination name of the recording",
125                                                         "paramType": "query",
126                                                         "required": true,
127                                                         "allowMultiple": false,
128                                                         "dataType": "string"
129                                                 }
130                                         ],
131                                         "errorResponses": [
132                                                 {
133                                                         "code": 404,
134                                                         "reason": "Recording not found"
135                                                 },
136                                                 {
137                                                         "code": 409,
138                                                         "reason": "A recording with the same name already exists on the system"
139                                                 }
140                                         ]
141                                 }
142                         ]
143                 },
144                 {
145                         "path": "/recordings/live/{recordingName}",
146                         "description": "A recording that is in progress",
147                         "operations": [
148                                 {
149                                         "httpMethod": "GET",
150                                         "summary": "List live recordings.",
151                                         "nickname": "getLive",
152                                         "responseClass": "LiveRecording",
153                                         "parameters": [
154                                                 {
155                                                         "name": "recordingName",
156                                                         "description": "The name of the recording",
157                                                         "paramType": "path",
158                                                         "required": true,
159                                                         "allowMultiple": false,
160                                                         "dataType": "string"
161                                                 }
162                                         ],
163                                         "errorResponses": [
164                                                 {
165                                                         "code": 404,
166                                                         "reason": "Recording not found"
167                                                 }
168                                         ]
169                                 },
170                                 {
171                                         "httpMethod": "DELETE",
172                                         "summary": "Stop a live recording and discard it.",
173                                         "nickname": "cancel",
174                                         "responseClass": "void",
175                                         "parameters": [
176                                                 {
177                                                         "name": "recordingName",
178                                                         "description": "The name of the recording",
179                                                         "paramType": "path",
180                                                         "required": true,
181                                                         "allowMultiple": false,
182                                                         "dataType": "string"
183                                                 }
184                                         ],
185                                         "errorResponses": [
186                                                 {
187                                                         "code": 404,
188                                                         "reason": "Recording not found"
189                                                 }
190                                         ]
191                                 }
192                         ]
193                 },
194                 {
195                         "path": "/recordings/live/{recordingName}/stop",
196                         "operations": [
197                                 {
198                                         "httpMethod": "POST",
199                                         "summary": "Stop a live recording and store it.",
200                                         "nickname": "stop",
201                                         "responseClass": "void",
202                                         "parameters": [
203                                                 {
204                                                         "name": "recordingName",
205                                                         "description": "The name of the recording",
206                                                         "paramType": "path",
207                                                         "required": true,
208                                                         "allowMultiple": false,
209                                                         "dataType": "string"
210                                                 }
211                                         ],
212                                         "errorResponses": [
213                                                 {
214                                                         "code": 404,
215                                                         "reason": "Recording not found"
216                                                 }
217                                         ]
218                                 }
219                         ]
220                 },
221                 {
222                         "path": "/recordings/live/{recordingName}/pause",
223                         "operations": [
224                                 {
225                                         "httpMethod": "POST",
226                                         "summary": "Pause a live recording.",
227                                         "notes": "Pausing a recording suspends silence detection, which will be restarted when the recording is unpaused. Paused time is not included in the accounting for maxDurationSeconds.",
228                                         "nickname": "pause",
229                                         "responseClass": "void",
230                                         "parameters": [
231                                                 {
232                                                         "name": "recordingName",
233                                                         "description": "The name of the recording",
234                                                         "paramType": "path",
235                                                         "required": true,
236                                                         "allowMultiple": false,
237                                                         "dataType": "string"
238                                                 }
239                                         ],
240                                         "errorResponses": [
241                                                 {
242                                                         "code": 404,
243                                                         "reason": "Recording not found"
244                                                 },
245                                                 {
246                                                         "code": 409,
247                                                         "reason": "Recording not in session"
248                                                 }
249                                         ]
250                                 },
251                                 {
252                                         "httpMethod": "DELETE",
253                                         "summary": "Unpause a live recording.",
254                                         "nickname": "unpause",
255                                         "responseClass": "void",
256                                         "parameters": [
257                                                 {
258                                                         "name": "recordingName",
259                                                         "description": "The name of the recording",
260                                                         "paramType": "path",
261                                                         "required": true,
262                                                         "allowMultiple": false,
263                                                         "dataType": "string"
264                                                 }
265                                         ],
266                                         "errorResponses": [
267                                                 {
268                                                         "code": 404,
269                                                         "reason": "Recording not found"
270                                                 },
271                                                 {
272                                                         "code": 409,
273                                                         "reason": "Recording not in session"
274                                                 }
275                                         ]
276                                 }
277                         ]
278                 },
279                 {
280                         "path": "/recordings/live/{recordingName}/mute",
281                         "operations": [
282                                 {
283                                         "httpMethod": "POST",
284                                         "summary": "Mute a live recording.",
285                                         "notes": "Muting a recording suspends silence detection, which will be restarted when the recording is unmuted.",
286                                         "nickname": "mute",
287                                         "responseClass": "void",
288                                         "parameters": [
289                                                 {
290                                                         "name": "recordingName",
291                                                         "description": "The name of the recording",
292                                                         "paramType": "path",
293                                                         "required": true,
294                                                         "allowMultiple": false,
295                                                         "dataType": "string"
296                                                 }
297                                         ],
298                                         "errorResponses": [
299                                                 {
300                                                         "code": 404,
301                                                         "reason": "Recording not found"
302                                                 },
303                                                 {
304                                                         "code": 409,
305                                                         "reason": "Recording not in session"
306                                                 }
307                                         ]
308                                 },
309                                 {
310                                         "httpMethod": "DELETE",
311                                         "summary": "Unmute a live recording.",
312                                         "nickname": "unmute",
313                                         "responseClass": "void",
314                                         "parameters": [
315                                                 {
316                                                         "name": "recordingName",
317                                                         "description": "The name of the recording",
318                                                         "paramType": "path",
319                                                         "required": true,
320                                                         "allowMultiple": false,
321                                                         "dataType": "string"
322                                                 }
323                                         ],
324                                         "errorResponses": [
325                                                 {
326                                                         "code": 404,
327                                                         "reason": "Recording not found"
328                                                 },
329                                                 {
330                                                         "code": 409,
331                                                         "reason": "Recording not in session"
332                                                 }
333                                         ]
334                                 }
335                         ]
336                 }
337         ],
338         "models": {
339                 "StoredRecording": {
340                         "id": "StoredRecording",
341                         "description": "A past recording that may be played back.",
342                         "properties": {
343                                 "name": {
344                                         "required": true,
345                                         "type": "string"
346                                 },
347                                 "format": {
348                                         "required": true,
349                                         "type": "string"
350                                 }
351                         }
352                 },
353                 "LiveRecording": {
354                         "id": "LiveRecording",
355                         "description": "A recording that is in progress",
356                         "properties": {
357                                 "name": {
358                                         "required": true,
359                                         "type": "string",
360                                         "description": "Base name for the recording"
361                                 },
362                                 "format": {
363                                         "required": true,
364                                         "type": "string",
365                                         "description": "Recording format (wav, gsm, etc.)"
366                                 },
367                                 "target_uri": {
368                                         "required": true,
369                                         "type": "string",
370                                         "description": "URI for the channel or bridge being recorded"
371                                 },
372                                 "state": {
373                                         "required": true,
374                                         "type": "string",
375                                         "allowableValues": {
376                                                 "valueType": "LIST",
377                                                 "values": [
378                                                         "queued",
379                                                         "recording",
380                                                         "paused",
381                                                         "done",
382                                                         "failed",
383                                                         "canceled"
384                                                 ]
385                                         }
386                                 },
387                                 "duration": {
388                                         "required": false,
389                                         "type": "int",
390                                         "description": "Duration in seconds of the recording"
391                                 },
392                                 "talking_duration": {
393                                         "required": false,
394                                         "type": "int",
395                                         "description": "Duration of talking, in seconds, detected in the recording. This is only available if the recording was initiated with a non-zero maxSilenceSeconds."
396                                 },
397                                 "silence_duration": {
398                                         "required": false,
399                                         "type": "int",
400                                         "description": "Duration of silence, in seconds, detected in the recording. This is only available if the recording was initiated with a non-zero maxSilenceSeconds."
401                                 },
402                                 "cause": {
403                                         "required": false,
404                                         "type": "string",
405                                         "description": "Cause for recording failure if failed"
406                                 }
407                         }
408                 }
409         }
410 }