AMI/ARI: Update version to 2.5.0/1.5.0 respectively
[asterisk/asterisk.git] / rest-api / api-docs / bridges.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.5.0",
6         "swaggerVersion": "1.1",
7         "basePath": "http://localhost:8088/stasis",
8         "resourcePath": "/api-docs/bridges.{format}",
9         "apis": [
10                 {
11                         "path": "/bridges",
12                         "description": "Active bridges",
13                         "operations": [
14                                 {
15                                         "httpMethod": "GET",
16                                         "summary": "List all active bridges in Asterisk.",
17                                         "nickname": "list",
18                                         "responseClass": "List[Bridge]"
19                                 },
20                                 {
21                                         "httpMethod": "POST",
22                                         "summary": "Create a new bridge.",
23                                         "notes": "This bridge persists until it has been shut down, or Asterisk has been shut down.",
24                                         "nickname": "create",
25                                         "responseClass": "Bridge",
26                                         "parameters": [
27                                                 {
28                                                         "name": "type",
29                                                         "description": "Comma separated list of bridge type attributes (mixing, holding, dtmf_events, proxy_media).",
30                                                         "paramType": "query",
31                                                         "required": false,
32                                                         "allowMultiple": false,
33                                                         "dataType": "string"
34                                                 },
35                                                 {
36                                                         "name": "bridgeId",
37                                                         "description": "Unique ID to give to the bridge being created.",
38                                                         "paramType": "query",
39                                                         "required": false,
40                                                         "allowMultiple": false,
41                                                         "dataType": "string"
42                                                 },
43                                                 {
44                                                         "name": "name",
45                                                         "description": "Name to give to the bridge being created.",
46                                                         "paramType": "query",
47                                                         "required": false,
48                                                         "allowMultiple": false,
49                                                         "dataType": "string"
50                                                 }
51                                         ]
52                                 }
53                         ]
54                 },
55                 {
56                         "path": "/bridges/{bridgeId}",
57                         "description": "Individual bridge",
58                         "operations": [
59                                 {
60                                         "httpMethod": "POST",
61                                         "summary": "Create a new bridge or updates an existing one.",
62                                         "notes": "This bridge persists until it has been shut down, or Asterisk has been shut down.",
63                                         "nickname": "create_or_update_with_id",
64                                         "responseClass": "Bridge",
65                                         "parameters": [
66                                                 {
67                                                         "name": "type",
68                                                         "description": "Comma separated list of bridge type attributes (mixing, holding, dtmf_events, proxy_media) to set.",
69                                                         "paramType": "query",
70                                                         "required": false,
71                                                         "allowMultiple": false,
72                                                         "dataType": "string"
73                                                 },
74                                                 {
75                                                         "name": "bridgeId",
76                                                         "description": "Unique ID to give to the bridge being created.",
77                                                         "paramType": "path",
78                                                         "required": true,
79                                                         "allowMultiple": false,
80                                                         "dataType": "string"
81                                                 },
82                                                 {
83                                                         "name": "name",
84                                                         "description": "Set the name of the bridge.",
85                                                         "paramType": "query",
86                                                         "required": false,
87                                                         "allowMultiple": false,
88                                                         "dataType": "string"
89                                                 }
90                                         ]
91                                 },
92                                 {
93                                         "httpMethod": "GET",
94                                         "summary": "Get bridge details.",
95                                         "nickname": "get",
96                                         "responseClass": "Bridge",
97                                         "parameters": [
98                                                 {
99                                                         "name": "bridgeId",
100                                                         "description": "Bridge's id",
101                                                         "paramType": "path",
102                                                         "required": true,
103                                                         "allowMultiple": false,
104                                                         "dataType": "string"
105                                                 }
106                                         ],
107                                         "errorResponses": [
108                                                 {
109                                                         "code": 404,
110                                                         "reason": "Bridge not found"
111                                                 }
112                                         ]
113                                 },
114                                 {
115                                         "httpMethod": "DELETE",
116                                         "summary": "Shut down a bridge.",
117                                         "notes": "If any channels are in this bridge, they will be removed and resume whatever they were doing beforehand.",
118                                         "nickname": "destroy",
119                                         "responseClass": "void",
120                                         "parameters": [
121                                                 {
122                                                         "name": "bridgeId",
123                                                         "description": "Bridge's id",
124                                                         "paramType": "path",
125                                                         "required": true,
126                                                         "allowMultiple": false,
127                                                         "dataType": "string"
128                                                 }
129                                         ],
130                                         "errorResponses": [
131                                                 {
132                                                         "code": 404,
133                                                         "reason": "Bridge not found"
134                                                 }
135                                         ]
136                                 }
137                         ]
138                 },
139                 {
140                         "path": "/bridges/{bridgeId}/addChannel",
141                         "description": "Add a channel to a bridge",
142                         "operations": [
143                                 {
144                                         "httpMethod": "POST",
145                                         "summary": "Add a channel to a bridge.",
146                                         "nickname": "addChannel",
147                                         "responseClass": "void",
148                                         "parameters": [
149                                                 {
150                                                         "name": "bridgeId",
151                                                         "description": "Bridge's id",
152                                                         "paramType": "path",
153                                                         "required": true,
154                                                         "allowMultiple": false,
155                                                         "dataType": "string"
156                                                 },
157                                                 {
158                                                         "name": "channel",
159                                                         "description": "Ids of channels to add to bridge",
160                                                         "paramType": "query",
161                                                         "required": true,
162                                                         "allowMultiple": true,
163                                                         "dataType": "string"
164                                                 },
165                                                 {
166                                                         "name": "role",
167                                                         "description": "Channel's role in the bridge",
168                                                         "paramType": "query",
169                                                         "required": false,
170                                                         "allowMultiple": false,
171                                                         "dataType": "string"
172                                                 }
173                                         ],
174                                         "errorResponses": [
175                                                 {
176                                                         "code": 400,
177                                                         "reason": "Channel not found"
178                                                 },
179                                                 {
180                                                         "code": 404,
181                                                         "reason": "Bridge not found"
182                                                 },
183                                                 {
184                                                         "code": 409,
185                                                         "reason": "Bridge not in Stasis application; Channel currently recording"
186                                                 },
187                                                 {
188                                                         "code": 422,
189                                                         "reason": "Channel not in Stasis application"
190                                                 }
191                                         ]
192                                 }
193                         ]
194                 },
195                 {
196                         "path": "/bridges/{bridgeId}/removeChannel",
197                         "description": "Remove a channel from a bridge",
198                         "operations": [
199                                 {
200                                         "httpMethod": "POST",
201                                         "summary": "Remove a channel from a bridge.",
202                                         "nickname": "removeChannel",
203                                         "responseClass": "void",
204                                         "parameters": [
205                                                 {
206                                                         "name": "bridgeId",
207                                                         "description": "Bridge's id",
208                                                         "paramType": "path",
209                                                         "required": true,
210                                                         "allowMultiple": false,
211                                                         "dataType": "string"
212                                                 },
213                                                 {
214                                                         "name": "channel",
215                                                         "description": "Ids of channels to remove from bridge",
216                                                         "paramType": "query",
217                                                         "required": true,
218                                                         "allowMultiple": true,
219                                                         "dataType": "string"
220                                                 }
221                                         ],
222                                         "errorResponses": [
223                                                 {
224                                                         "code": 400,
225                                                         "reason": "Channel not found"
226                                                 },
227                                                 {
228                                                         "code": 404,
229                                                         "reason": "Bridge not found"
230                                                 },
231                                                 {
232                                                         "code": 409,
233                                                         "reason": "Bridge not in Stasis application"
234                                                 },
235                                                 {
236                                                         "code": 422,
237                                                         "reason": "Channel not in this bridge"
238                                                 }
239                                         ]
240                                 }
241                         ]
242                 },
243                 {
244                         "path": "/bridges/{bridgeId}/moh",
245                         "description": "Play music on hold to a bridge",
246                         "operations": [
247                                 {
248                                         "httpMethod": "POST",
249                                         "summary": "Play music on hold to a bridge or change the MOH class that is playing.",
250                                         "nickname": "startMoh",
251                                         "responseClass": "void",
252                                         "parameters": [
253                                                 {
254                                                         "name": "bridgeId",
255                                                         "description": "Bridge's id",
256                                                         "paramType": "path",
257                                                         "required": true,
258                                                         "allowMultiple": false,
259                                                         "dataType": "string"
260                                                 },
261                                                 {
262                                                         "name": "mohClass",
263                                                         "description": "Channel's id",
264                                                         "paramType": "query",
265                                                         "required": false,
266                                                         "allowMultiple": false,
267                                                         "dataType": "string"
268                                                 }
269                                         ],
270                                         "errorResponses": [
271                                                 {
272                                                         "code": 404,
273                                                         "reason": "Bridge not found"
274                                                 },
275                                                 {
276                                                         "code": 409,
277                                                         "reason": "Bridge not in Stasis application"
278                                                 }
279                                         ]
280                                 },
281                                 {
282                                         "httpMethod": "DELETE",
283                                         "summary": "Stop playing music on hold to a bridge.",
284                                         "notes": "This will only stop music on hold being played via POST bridges/{bridgeId}/moh.",
285                                         "nickname": "stopMoh",
286                                         "responseClass": "void",
287                                         "parameters": [
288                                                 {
289                                                         "name": "bridgeId",
290                                                         "description": "Bridge's id",
291                                                         "paramType": "path",
292                                                         "required": true,
293                                                         "allowMultiple": false,
294                                                         "dataType": "string"
295                                                 }
296                                         ],
297                                         "errorResponses": [
298                                                 {
299                                                         "code": 404,
300                                                         "reason": "Bridge not found"
301                                                 },
302                                                 {
303                                                         "code": 409,
304                                                         "reason": "Bridge not in Stasis application"
305                                                 }
306                                         ]
307                                 }
308                         ]
309                 },
310                 {
311                         "path": "/bridges/{bridgeId}/play",
312                         "description": "Play media to the participants of a bridge",
313                         "operations": [
314                                 {
315                                         "httpMethod": "POST",
316                                         "summary": "Start playback of media on a bridge.",
317                                         "notes": "The media URI may be any of a number of URI's. Currently sound:, recording:, number:, digits:, characters:, and tone: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
318                                         "nickname": "play",
319                                         "responseClass": "Playback",
320                                         "parameters": [
321                                                 {
322                                                         "name": "bridgeId",
323                                                         "description": "Bridge's id",
324                                                         "paramType": "path",
325                                                         "required": true,
326                                                         "allowMultiple": false,
327                                                         "dataType": "string"
328                                                 },
329                                                 {
330                                                         "name": "media",
331                                                         "description": "Media's URI to play.",
332                                                         "paramType": "query",
333                                                         "required": true,
334                                                         "allowMultiple": false,
335                                                         "dataType": "string"
336                                                 },
337                                                 {
338                                                         "name": "lang",
339                                                         "description": "For sounds, selects language for sound.",
340                                                         "paramType": "query",
341                                                         "required": false,
342                                                         "allowMultiple": false,
343                                                         "dataType": "string"
344                                                 },
345                                                 {
346                                                         "name": "offsetms",
347                                                         "description": "Number of media to skip before playing.",
348                                                         "paramType": "query",
349                                                         "required": false,
350                                                         "allowMultiple": false,
351                                                         "dataType": "int",
352                                                         "defaultValue": 0,
353                                                         "allowableValues": {
354                                                                 "valueType": "RANGE",
355                                                                 "min": 0
356                                                         }
357
358                                                 },
359                                                 {
360                                                         "name": "skipms",
361                                                         "description": "Number of milliseconds to skip for forward/reverse operations.",
362                                                         "paramType": "query",
363                                                         "required": false,
364                                                         "allowMultiple": false,
365                                                         "dataType": "int",
366                                                         "defaultValue": 3000,
367                                                         "allowableValues": {
368                                                                 "valueType": "RANGE",
369                                                                 "min": 0
370                                                         }
371                                                 },
372                                                 {
373                                                         "name": "playbackId",
374                                                         "description": "Playback Id.",
375                                                         "paramType": "query",
376                                                         "required": false,
377                                                         "allowMultiple": false,
378                                                         "dataType": "string"
379                                                 }
380                                         ],
381                                         "errorResponses": [
382                                                 {
383                                                         "code": 404,
384                                                         "reason": "Bridge not found"
385                                                 },
386                                                 {
387                                                         "code": 409,
388                                                         "reason": "Bridge not in a Stasis application"
389                                                 }
390                                         ]
391                                 }
392                         ]
393                 },
394                 {
395                         "path": "/bridges/{bridgeId}/play/{playbackId}",
396                         "description": "Play media to a bridge",
397                         "operations": [
398                                 {
399                                         "httpMethod": "POST",
400                                         "summary": "Start playback of media on a bridge.",
401                                         "notes": "The media URI may be any of a number of URI's. Currently sound: and recording: URI's are supported. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
402                                         "nickname": "playWithId",
403                                         "responseClass": "Playback",
404                                         "parameters": [
405                                                 {
406                                                         "name": "bridgeId",
407                                                         "description": "Bridge's id",
408                                                         "paramType": "path",
409                                                         "required": true,
410                                                         "allowMultiple": false,
411                                                         "dataType": "string"
412                                                 },
413                                                 {
414                                                         "name": "playbackId",
415                                                         "description": "Playback ID.",
416                                                         "paramType": "path",
417                                                         "required": true,
418                                                         "allowMultiple": false,
419                                                         "dataType": "string"
420                                                 },
421                                                 {
422                                                         "name": "media",
423                                                         "description": "Media's URI to play.",
424                                                         "paramType": "query",
425                                                         "required": true,
426                                                         "allowMultiple": false,
427                                                         "dataType": "string"
428                                                 },
429                                                 {
430                                                         "name": "lang",
431                                                         "description": "For sounds, selects language for sound.",
432                                                         "paramType": "query",
433                                                         "required": false,
434                                                         "allowMultiple": false,
435                                                         "dataType": "string"
436                                                 },
437                                                 {
438                                                         "name": "offsetms",
439                                                         "description": "Number of media to skip before playing.",
440                                                         "paramType": "query",
441                                                         "required": false,
442                                                         "allowMultiple": false,
443                                                         "dataType": "int",
444                                                         "defaultValue": 0,
445                                                         "allowableValues": {
446                                                                 "valueType": "RANGE",
447                                                                 "min": 0
448                                                         }
449                                                 },
450                                                 {
451                                                         "name": "skipms",
452                                                         "description": "Number of milliseconds to skip for forward/reverse operations.",
453                                                         "paramType": "query",
454                                                         "required": false,
455                                                         "allowMultiple": false,
456                                                         "dataType": "int",
457                                                         "defaultValue": 3000,
458                                                         "allowableValues": {
459                                                                 "valueType": "RANGE",
460                                                                 "min": 0
461                                                         }
462                                                 }
463                                         ],
464                                         "errorResponses": [
465                                                 {
466                                                         "code": 404,
467                                                         "reason": "Bridge not found"
468                                                 },
469                                                 {
470                                                         "code": 409,
471                                                         "reason": "Bridge not in a Stasis application"
472                                                 }
473                                         ]
474
475                                 }
476                         ]
477                 },
478                 {
479                         "path": "/bridges/{bridgeId}/record",
480                         "description": "Record audio on a bridge",
481                         "operations": [
482                                 {
483                                         "httpMethod": "POST",
484                                         "summary": "Start a recording.",
485                                         "notes": "This records the mixed audio from all channels participating in this bridge.",
486                                         "nickname": "record",
487                                         "responseClass": "LiveRecording",
488                                         "parameters": [
489                                                 {
490                                                         "name": "bridgeId",
491                                                         "description": "Bridge's id",
492                                                         "paramType": "path",
493                                                         "required": true,
494                                                         "allowMultiple": false,
495                                                         "dataType": "string"
496                                                 },
497                                                 {
498                                                         "name": "name",
499                                                         "description": "Recording's filename",
500                                                         "paramType": "query",
501                                                         "required": true,
502                                                         "allowMultiple": false,
503                                                         "dataType": "string"
504                                                 },
505                                                 {
506                                                         "name": "format",
507                                                         "description": "Format to encode audio in",
508                                                         "paramType": "query",
509                                                         "required": true,
510                                                         "allowMultiple": false,
511                                                         "dataType": "string"
512                                                 },
513                                                 {
514                                                         "name": "maxDurationSeconds",
515                                                         "description": "Maximum duration of the recording, in seconds. 0 for no limit.",
516                                                         "paramType": "query",
517                                                         "required": false,
518                                                         "allowMultiple": false,
519                                                         "dataType": "int",
520                                                         "defaultValue": 0,
521                                                         "allowableValues": {
522                                                                 "valueType": "RANGE",
523                                                                 "min": 0
524                                                         }
525                                                 },
526                                                 {
527                                                         "name": "maxSilenceSeconds",
528                                                         "description": "Maximum duration of silence, in seconds. 0 for no limit.",
529                                                         "paramType": "query",
530                                                         "required": false,
531                                                         "allowMultiple": false,
532                                                         "dataType": "int",
533                                                         "defaultValue": 0,
534                                                         "allowableValues": {
535                                                                 "valueType": "RANGE",
536                                                                 "min": 0
537                                                         }
538                                                 },
539                                                 {
540                                                         "name": "ifExists",
541                                                         "description": "Action to take if a recording with the same name already exists.",
542                                                         "paramType": "query",
543                                                         "required": false,
544                                                         "allowMultiple": false,
545                                                         "dataType": "string",
546                                                         "defaultValue": "fail",
547                                                         "allowableValues": {
548                                                                 "valueType": "LIST",
549                                                                 "values": [
550                                                                         "fail",
551                                                                         "overwrite",
552                                                                         "append"
553                                                                 ]
554                                                         }
555                                                 },
556                                                 {
557                                                         "name": "beep",
558                                                         "description": "Play beep when recording begins",
559                                                         "paramType": "query",
560                                                         "required": false,
561                                                         "allowMultiple": false,
562                                                         "dataType": "boolean",
563                                                         "defaultValue": false
564                                                 },
565                                                 {
566                                                         "name": "terminateOn",
567                                                         "description": "DTMF input to terminate recording.",
568                                                         "paramType": "query",
569                                                         "required": false,
570                                                         "allowMultiple": false,
571                                                         "dataType": "string",
572                                                         "defaultValue": "none",
573                                                         "allowableValues": {
574                                                                 "valueType": "LIST",
575                                                                 "values": [
576                                                                         "none",
577                                                                         "any",
578                                                                         "*",
579                                                                         "#"
580                                                                 ]
581                                                         }
582                                                 }
583                                         ],
584                     "errorResponses": [
585                         {
586                             "code": 400,
587                             "reason": "Invalid parameters"
588                         },
589                         {
590                             "code": 404,
591                             "reason": "Bridge not found"
592                         },
593                         {
594                             "code": 409,
595                             "reason": "Bridge is not in a Stasis application; A recording with the same name already exists on the system and can not be overwritten because it is in progress or ifExists=fail"
596                         },
597                                                 {
598                                                         "code": 422,
599                                                         "reason": "The format specified is unknown on this system"
600                                                 }
601                     ]
602                                 }
603                         ]
604                 }
605         ],
606         "models": {
607                 "Bridge": {
608                         "id": "Bridge",
609                         "description": "The merging of media from one or more channels.\n\nEveryone on the bridge receives the same audio.",
610                         "properties": {
611                                 "id": {
612                                         "type": "string",
613                                         "description": "Unique identifier for this bridge",
614                                         "required": true
615                                 },
616                                 "technology": {
617                                         "type": "string",
618                                         "description": "Name of the current bridging technology",
619                                         "required": true
620                                 },
621                                 "bridge_type": {
622                                         "type": "string",
623                                         "description": "Type of bridge technology",
624                                         "required": true,
625                                         "allowableValues": {
626                                                 "valueType": "LIST",
627                                                 "values": [
628                                                         "mixing",
629                                                         "holding"
630                                                 ]
631                                         }
632                                 },
633                                 "bridge_class": {
634                                         "type": "string",
635                                         "description": "Bridging class",
636                                         "required": true
637                                 },
638                                 "creator": {
639                                         "type": "string",
640                                         "description": "Entity that created the bridge",
641                                         "required": true
642                                 },
643                                 "name": {
644                                         "type": "string",
645                                         "description": "Name the creator gave the bridge",
646                                         "required": true
647                                 },
648                                 "channels": {
649                                         "type": "List[string]",
650                                         "description": "Ids of channels participating in this bridge",
651                                         "required": true
652                                 }
653                         }
654                 }
655         }
656 }