This patch adds a RESTful HTTP interface to Asterisk.
[asterisk/asterisk.git] / rest-api / api-docs / channels.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": "0.0.1",
6         "swaggerVersion": "1.1",
7         "basePath": "http://localhost:8088/stasis",
8         "resourcePath": "/api-docs/channels.{format}",
9         "apis": [
10                 {
11                         "path": "/channels",
12                         "description": "Active channels",
13                         "operations": [
14                                 {
15                                         "httpMethod": "GET",
16                                         "summary": "List active channels.",
17                                         "nickname": "getChannels",
18                                         "responseClass": "List[Channel]"
19                                 },
20                                 {
21                                         "httpMethod": "POST",
22                                         "summary": "Create a new channel (originate).",
23                                         "nickname": "originate",
24                                         "responseClass": "Originated",
25                                         "parameters": [
26                                                 {
27                                                         "name": "endpoint",
28                                                         "description": "Endpoint to call. If not specified, originate is routed via dialplan",
29                                                         "paramType": "query",
30                                                         "required": false,
31                                                         "allowMultiple": false,
32                                                         "dataType": "string"
33                                                 },
34                                                 {
35                                                         "name": "extension",
36                                                         "description": "Extension to dial",
37                                                         "paramType": "query",
38                                                         "required": false,
39                                                         "allowMultiple": false,
40                                                         "dataType": "string"
41                                                 },
42                                                 {
43                                                         "name": "context",
44                                                         "description": "When routing via dialplan, the context use. If omitted, uses 'default'",
45                                                         "paramType": "query",
46                                                         "required": false,
47                                                         "allowMultiple": false,
48                                                         "dataType": "string"
49                                                 }
50                                         ]
51                                 }
52                         ]
53                 },
54                 {
55                         "path": "/channels/{channelId}",
56                         "description": "Active channel",
57                         "operations": [
58                                 {
59                                         "httpMethod": "GET",
60                                         "summary": "Channel details.",
61                                         "nickname": "getChannel",
62                                         "responseClass": "Channel",
63                                         "parameters": [
64                                                 {
65                                                         "name": "channelId",
66                                                         "description": "Channel's id",
67                                                         "paramType": "path",
68                                                         "required": true,
69                                                         "allowMultiple": false,
70                                                         "dataType": "string"
71                                                 }
72                                         ],
73                                         "errorResponses": [
74                                                 {
75                                                         "code": 404,
76                                                         "reason": "Channel not found"
77                                                 }
78                                         ]
79                                 },
80                                 {
81                                         "httpMethod": "DELETE",
82                                         "summary": "Delete (i.e. hangup) a channel.",
83                                         "nickname": "deleteChannel",
84                                         "responseClass": "void",
85                                         "parameters": [
86                                                 {
87                                                         "name": "channelId",
88                                                         "description": "Channel's id",
89                                                         "paramType": "path",
90                                                         "required": true,
91                                                         "allowMultiple": false,
92                                                         "dataType": "string"
93                                                 }
94                                         ],
95                                         "errorResponses": [
96                                                 {
97                                                         "code": 404,
98                                                         "reason": "Channel not found"
99                                                 }
100                                         ]
101                                 }
102                         ]
103                 },
104                 {
105                         "path": "/channels/{channelId}/dial",
106                         "description": "Create a new channel (originate) and bridge to this channel",
107                         "operations": [
108                                 {
109                                         "httpMethod": "POST",
110                                         "summary": "Create a new channel (originate) and bridge to this channel.",
111                                         "nickname": "dial",
112                                         "responseClass": "Dialed",
113                                         "parameters": [
114                                                 {
115                                                         "name": "channelId",
116                                                         "description": "Channel's id",
117                                                         "paramType": "path",
118                                                         "required": true,
119                                                         "allowMultiple": false,
120                                                         "dataType": "string"
121                                                 },
122                                                 {
123                                                         "name": "endpoint",
124                                                         "description": "Endpoint to call. If not specified, dial is routed via dialplan",
125                                                         "paramType": "query",
126                                                         "required": false,
127                                                         "allowMultiple": false,
128                                                         "dataType": "string"
129                                                 },
130                                                 {
131                                                         "name": "extension",
132                                                         "description": "Extension to dial",
133                                                         "paramType": "query",
134                                                         "required": false,
135                                                         "allowMultiple": false,
136                                                         "dataType": "string"
137                                                 },
138                                                 {
139                                                         "name": "context",
140                                                         "description": "When routing via dialplan, the context use. If omitted, uses 'default'",
141                                                         "paramType": "query",
142                                                         "required": false,
143                                                         "allowMultiple": false,
144                                                         "dataType": "string"
145                                                 }
146                                         ],
147                                         "errorResponses": [
148                                                 {
149                                                         "code": 404,
150                                                         "reason": "Channel not found"
151                                                 },
152                                                 {
153                                                         "code": 409,
154                                                         "reason": "Channel not in a Stasis application"
155                                                 }
156                                         ]
157                                 }
158                         ]
159                 },
160                 {
161                         "path": "/channels/{channelId}/continue",
162                         "description": "Exit application; continue execution in the dialplan",
163                         "operations": [
164                                 {
165                                         "httpMethod": "POST",
166                                         "summary": "Exit application; continue execution in the dialplan.",
167                                         "nickname": "continueInDialplan",
168                                         "responseClass": "void",
169                                         "parameters": [
170                                                 {
171                                                         "name": "channelId",
172                                                         "description": "Channel's id",
173                                                         "paramType": "path",
174                                                         "required": true,
175                                                         "allowMultiple": false,
176                                                         "dataType": "string"
177                                                 }
178                                         ],
179                                         "errorResponses": [
180                                                 {
181                                                         "code": 404,
182                                                         "reason": "Channel not found"
183                                                 },
184                                                 {
185                                                         "code": 409,
186                                                         "reason": "Channel not in a Stasis application"
187                                                 }
188                                         ]
189                                 }
190                         ]
191                 },
192                 {
193                         "path": "/channels/{channelId}/answer",
194                         "description": "Answer a channel",
195                         "operations": [
196                                 {
197                                         "httpMethod": "POST",
198                                         "summary": "Answer a channel.",
199                                         "nickname": "answerChannel",
200                                         "responseClass": "void",
201                                         "parameters": [
202                                                 {
203                                                         "name": "channelId",
204                                                         "description": "Channel's id",
205                                                         "paramType": "path",
206                                                         "required": true,
207                                                         "allowMultiple": false,
208                                                         "dataType": "string"
209                                                 }
210                                         ],
211                                         "errorResponses": [
212                                                 {
213                                                         "code": 404,
214                                                         "reason": "Channel not found"
215                                                 }
216                                         ]
217                                 }
218                         ]
219                 },
220                 {
221                         "path": "/channels/{channelId}/mute",
222                         "description": "Mute a channel",
223                         "operations": [
224                                 {
225                                         "httpMethod": "POST",
226                                         "summary": "Mute a channel.",
227                                         "nickname": "muteChannel",
228                                         "responseClass": "void",
229                                         "parameters": [
230                                                 {
231                                                         "name": "channelId",
232                                                         "description": "Channel's id",
233                                                         "paramType": "path",
234                                                         "required": true,
235                                                         "allowMultiple": false,
236                                                         "dataType": "string"
237                                                 },
238                                                 {
239                                                         "name": "direction",
240                                                         "description": "Direction in which to mute audio",
241                                                         "paramType": "query",
242                                                         "required": false,
243                                                         "allowMultiple": false,
244                                                         "dataType": "string",
245                                                         "defaultValue": "both",
246                                                         "allowableValues": {
247                                                                 "valueType": "LIST",
248                                                                 "values": [
249                                                                         "both",
250                                                                         "in",
251                                                                         "out"
252                                                                 ]
253                                                         }
254                                                 }
255                                         ],
256                                         "errorResponses": [
257                                                 {
258                                                         "code": 404,
259                                                         "reason": "Channel not found"
260                                                 },
261                                                 {
262                                                         "code": 409,
263                                                         "reason": "Channel not in a Stasis application"
264                                                 }
265                                         ]
266                                 }
267                         ]
268                 },
269                 {
270                         "path": "/channels/{channelId}/unmute",
271                         "description": "Unmute a channel",
272                         "operations": [
273                                 {
274                                         "httpMethod": "POST",
275                                         "summary": "Unmute a channel.",
276                                         "nickname": "unmuteChannel",
277                                         "responseClass": "void",
278                                         "parameters": [
279                                                 {
280                                                         "name": "channelId",
281                                                         "description": "Channel's id",
282                                                         "paramType": "path",
283                                                         "required": true,
284                                                         "allowMultiple": false,
285                                                         "dataType": "string"
286                                                 },
287                                                 {
288                                                         "name": "direction",
289                                                         "description": "Direction in which to unmute audio",
290                                                         "paramType": "query",
291                                                         "required": false,
292                                                         "allowMultiple": false,
293                                                         "dataType": "string",
294                                                         "defaultValue": "both",
295                                                         "allowableValues": {
296                                                                 "valueType": "LIST",
297                                                                 "values": [
298                                                                         "both",
299                                                                         "in",
300                                                                         "out"
301                                                                 ]
302                                                         }
303                                                 }
304                                         ],
305                                         "errorResponses": [
306                                                 {
307                                                         "code": 404,
308                                                         "reason": "Channel not found"
309                                                 },
310                                                 {
311                                                         "code": 409,
312                                                         "reason": "Channel not in a Stasis application"
313                                                 }
314                                         ]
315                                 }
316                         ]
317                 },
318                 {
319                         "path": "/channels/{channelId}/hold",
320                         "description": "Put a channel on hold",
321                         "operations": [
322                                 {
323                                         "httpMethod": "POST",
324                                         "summary": "Hold a channel.",
325                                         "nickname": "holdChannel",
326                                         "responseClass": "void",
327                                         "parameters": [
328                                                 {
329                                                         "name": "channelId",
330                                                         "description": "Channel's id",
331                                                         "paramType": "path",
332                                                         "required": true,
333                                                         "allowMultiple": false,
334                                                         "dataType": "string"
335                                                 }
336                                         ],
337                                         "errorResponses": [
338                                                 {
339                                                         "code": 404,
340                                                         "reason": "Channel not found"
341                                                 },
342                                                 {
343                                                         "code": 409,
344                                                         "reason": "Channel not in a Stasis application"
345                                                 }
346                                         ]
347                                 }
348                         ]
349                 },
350                 {
351                         "path": "/channels/{channelId}/unhold",
352                         "description": "Remove a channel from hold",
353                         "operations": [
354                                 {
355                                         "httpMethod": "POST",
356                                         "summary": "Remove a channel from hold.",
357                                         "nickname": "unholdChannel",
358                                         "responseClass": "void",
359                                         "parameters": [
360                                                 {
361                                                         "name": "channelId",
362                                                         "description": "Channel's id",
363                                                         "paramType": "path",
364                                                         "required": true,
365                                                         "allowMultiple": false,
366                                                         "dataType": "string"
367                                                 }
368                                         ],
369                                         "errorResponses": [
370                                                 {
371                                                         "code": 404,
372                                                         "reason": "Channel not found"
373                                                 },
374                                                 {
375                                                         "code": 409,
376                                                         "reason": "Channel not in a Stasis application"
377                                                 }
378                                         ]
379                                 }
380                         ]
381                 },
382                 {
383                         "path": "/channels/{channelId}/play",
384                         "description": "Play media to a channel",
385                         "operations": [
386                                 {
387                                         "httpMethod": "POST",
388                                         "summary": "Start playback of media.",
389                                         "notes": "The media URI may be any of a number of URI's. You may use http: and https: URI's, as well as sound: and recording: URI's. This operation creates a playback resource that can be used to control the playback of media (pause, rewind, fast forward, etc.)",
390                                         "nickname": "playOnChannel",
391                                         "responseClass": "Playback",
392                                         "parameters": [
393                                                 {
394                                                         "name": "channelId",
395                                                         "description": "Channel's id",
396                                                         "paramType": "path",
397                                                         "required": true,
398                                                         "allowMultiple": false,
399                                                         "dataType": "string"
400                                                 },
401                                                 {
402                                                         "name": "media",
403                                                         "description": "Media's URI to play.",
404                                                         "paramType": "query",
405                                                         "required": true,
406                                                         "allowMultiple": false,
407                                                         "dataType": "string"
408                                                 }
409                                         ],
410                                         "errorResponses": [
411                                                 {
412                                                         "code": 404,
413                                                         "reason": "Channel not found"
414                                                 },
415                                                 {
416                                                         "code": 409,
417                                                         "reason": "Channel not in a Stasis application"
418                                                 }
419                                         ]
420                                 }
421                         ]
422                 },
423                 {
424                         "path": "/channels/{channelId}/record",
425                         "description": "Record audio from a channel",
426                         "operations": [
427                                 {
428                                         "httpMethod": "POST",
429                                         "summary": "Start a recording.",
430                                         "notes": "Record audio from a channel. Note that this will not capture audio sent to the channel. The bridge itself has a record feature if that's what you want.",
431                                         "nickname": "recordChannel",
432                                         "responseClass": "void",
433                                         "parameters": [
434                                                 {
435                                                         "name": "channelId",
436                                                         "description": "Channel's id",
437                                                         "paramType": "path",
438                                                         "required": true,
439                                                         "allowMultiple": false,
440                                                         "dataType": "string"
441                                                 },
442                                                 {
443                                                         "name": "name",
444                                                         "description": "Recording's filename",
445                                                         "paramType": "query",
446                                                         "required": true,
447                                                         "allowMultiple": false,
448                                                         "dataType": "string"
449                                                 },
450                                                 {
451                                                         "name": "format",
452                                                         "description": "Format to encode audio in",
453                                                         "paramType": "query",
454                                                         "required": true,
455                                                         "allowMultiple": true,
456                                                         "dataType": "string"
457                                                 },
458                                                 {
459                                                         "name": "maxDurationSeconds",
460                                                         "description": "Maximum duration of the recording, in seconds. 0 for no limit",
461                                                         "paramType": "query",
462                                                         "required": false,
463                                                         "allowMultiple": false,
464                                                         "dataType": "int",
465                                                         "defaultValue": 0
466                                                 },
467                                                 {
468                                                         "name": "maxSilenceSeconds",
469                                                         "description": "Maximum duration of silence, in seconds. 0 for no limit",
470                                                         "paramType": "query",
471                                                         "required": false,
472                                                         "allowMultiple": false,
473                                                         "dataType": "int",
474                                                         "defaultValue": 0
475                                                 },
476                                                 {
477                                                         "name": "append",
478                                                         "description": "If true, and recording already exists, append to recording",
479                                                         "paramType": "query",
480                                                         "required": false,
481                                                         "allowMultiple": false,
482                                                         "dataType": "boolean",
483                                                         "defaultValue": false
484                                                 },
485                                                 {
486                                                         "name": "beep",
487                                                         "description": "Play beep when recording begins",
488                                                         "paramType": "query",
489                                                         "required": false,
490                                                         "allowMultiple": false,
491                                                         "dataType": "boolean",
492                                                         "defaultValue": false
493                                                 },
494                                                 {
495                                                         "name": "terminateOn",
496                                                         "description": "DTMF input to terminate recording",
497                                                         "paramType": "query",
498                                                         "required": false,
499                                                         "allowMultiple": false,
500                                                         "dataType": "string",
501                                                         "defaultValue": "none",
502                                                         "allowableValues": {
503                                                                 "valueType": "LIST",
504                                                                 "values": [
505                                                                         "none",
506                                                                         "any",
507                                                                         "*",
508                                                                         "#"
509                                                                 ]
510                                                         }
511                                                 }
512                                         ],
513                                         "errorResponses": [
514                                                 {
515                                                         "code": 404,
516                                                         "reason": "Channel not found"
517                                                 },
518                                                 {
519                                                         "code": 409,
520                                                         "reason": "Channel is not in a Stasis application."
521                                                 },
522                                                 {
523                                                         "code": 409,
524                                                         "reason": "The channel is currently bridges with other channels."
525                                                 }
526                                         ]
527                                 }
528                         ]
529                 }
530         ],
531         "models": {
532                 "Originated": {
533                         "id": "Originated",
534                         "properties": {}
535                 },
536                 "Dialed": {
537                         "id": "Dialed",
538                         "properties": {}
539                 },
540                 "DialplanCEP": {
541                         "id": "DialplanCEP",
542                         "properties": {
543                                 "context": {
544                                         "required": true,
545                                         "type": "string",
546                                         "description": "Context in the dialplan"
547                                 },
548                                 "exten": {
549                                         "required": true,
550                                         "type": "string",
551                                         "description": "Extension in the dialplan"
552                                 },
553                                 "priority": {
554                                         "required": true,
555                                         "type": "long",
556                                         "description": "Priority in the dialplan"
557                                 }
558                         }
559                 },
560                 "CallerID": {
561                         "id": "CallerID",
562                         "properties": {
563                                 "name": {
564                                         "required": true,
565                                         "type": "string"
566                                 },
567                                 "number": {
568                                         "required": true,
569                                         "type": "string"
570                                 }
571                         }
572                 },
573                 "Channel": {
574                         "id": "Channel",
575                         "properties": {
576                                 "uniqueid": {
577                                         "required": true,
578                                         "type": "string",
579                                         "description": "Unique identifier of the channel"
580                                 },
581                                 "name": {
582                                         "required": true,
583                                         "type": "string",
584                                         "description": "Name of the channel (i.e. SIP/foo-0000a7e3)"
585                                 },
586                                 "state": {
587                                         "required": true,
588                                         "type": "string"
589                                 },
590                                 "accountcode": {
591                                         "required": true,
592                                         "type": "string"
593                                 },
594                                 "peeraccount": {
595                                         "required": true,
596                                         "type": "string"
597                                 },
598                                 "userfield": {
599                                         "required": true,
600                                         "type": "string"
601                                 },
602                                 "linkedid": {
603                                         "required": true,
604                                         "type": "string"
605                                 },
606                                 "parkinglot": {
607                                         "required": true,
608                                         "type": "string"
609                                 },
610                                 "hangupsource": {
611                                         "required": true,
612                                         "type": "string"
613                                 },
614                                 "appl": {
615                                         "required": true,
616                                         "type": "string",
617                                         "description": "Currently executing dialplan application"
618                                 },
619                                 "data": {
620                                         "required": true,
621                                         "type": "string",
622                                         "description": "Arguments passed to appl"
623                                 },
624                                 "dialplan": {
625                                         "required": true,
626                                         "type": "DialplanCEP",
627                                         "description": "Current location in the dialplan"
628                                 },
629                                 "caller": {
630                                         "required": true,
631                                         "type": "CallerID"
632                                 },
633                                 "connected": {
634                                         "required": true,
635                                         "type": "CallerID"
636                                 },
637                                 "creationtime": {
638                                         "required": true,
639                                         "type": "Date",
640                                         "description": "Timestamp when channel was created"
641                                 }
642                         }
643                 }
644         }
645 }