forked from ciscocms/apiary
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathapiary.apib
9994 lines (8663 loc) · 457 KB
/
apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
VerifyinFORMAT: 1A
HOST: http://cmsapi.cisco.io/api/v1
# Cisco Meeting Server API
The Cisco Meeting Server software can be hosted on specific servers based on Cisco Unified Computing Server (UCS) technology as well as on the Acano X-Series hardware, or on a
specification-based VM server. Cisco Meeting Server is referred to as the Meeting Server throughout this document.
This document covers version 2.8 and later of the Application Program Interface for the Cisco Meeting server. For version specific API changes, refer to the [Release Notes for Cisco Meeting Server](https://www.cisco.com/c/en/us/support/conferencing/meeting-server/products-programming-reference-guides-list.html).
In addition to this reference you can find documentation for Cisco Meeting Server [here](https://www.cisco.com/c/en/us/support/conferencing/meeting-server/tsd-products-support-series-home.html).
## General Structure of Methods
The Meeting Server‘s Application Programming Interface (API) is designed as a hierarchy of objects, like the trunk and roots of a tree.
For example, each configured coSpace exists as a node in this tree, and all of the users who are members of that coSpace exist as nodes
“beneath” the coSpace object’s node. The API objects are accessed using a suitable REST client.
---
Note: Cisco Meeting Server software version 3.0 does not support X-Series servers.
---
---
**Note:** Although the Cisco Meeting App and other Cisco Meeting Server guides refer to "spaces" rather than "coSpaces", the API still uses `/coSpace` objects.
---
The Meeting Server has the potential to host a large number of active calls and coSpaces. To reduce the overhead of retrieving the entire collection of objects in a single response, responses
typically return the first “N” matching entries and a count of the total number of objects of that type. To find an individual object’s active status, or to modify or delete it, use filters on the initial retrieval in order to identify the object in question.
### Object Hierarchy
The hierarchy of objects addressable via the API is:
`/accessQuery`
`/callBrandingProfiles`
`/callBrandingProfiles/<call branding profile id>`
`/callBridges`
`/callBridges/<call bridge id>`
`/calls`
`/calls/<call id>`
`/calls/<call id>/callLegs`
`/calls/<call id>/diagnostics`
`/calls/<call id>/participants`
`/callProfiles`
`/callProfiles/<call profile id>`
`/callLegs`
`/callLegs/<callLeg id>`
`/callLegs/<callLeg id>/callLegProfileTrace`
`/callLegProfiles`
`/callLegProfiles/<call leg profile id>`
`/callLegProfiles/<call leg profile id>/usage`
/clusterLicensing(3.0 onwards)
/clusterLicensing/raw(3.0 onwards)
/compatibilityProfiles (2.1 onwards)
/compatibilityProfiles/<compatibility profile id> (2.1 onwards)
/conversationIdQuery (2.3 onwards)
/cospaceBulkParameterSets(2.0 onwards)
/cospaceBulkParameterSets/<coSpace bulk parameter set id> (2.0 onwards)
/cospaceBulkSyncs(2.0 onwards)
/cospaceBulkSyncs/<coSpace bulk sync id>(2.0 onwards)
`/coSpaces`
`/coSpaces/<coSpace id>`
`/coSpaces/<coSpace id>/accessMethods`
`/coSpaces/<coSpace id>/accessMethods/<access method id>`
`/coSpaces/<coSpace id>/coSpaceUsers`
`/coSpaces/<coSpace id>/coSpaceUsers/<coSpaceUser id>`
`/coSpaces/<coSpace id>/diagnostics`
`/coSpaces/<coSpace id>/messages` (3.0 removed)
/coSpaceTemplates (2.9 onwards)
/coSpaceTemplates/<coSpace template id> (2.9 onwards)
/coSpaceTemplates/<coSpace template id>/accessMethodTemplates (2.9 onwards)
/coSpaceTemplates/<coSpace template id>/accessMethodTemplates/<access method
template id> (2.9 onwards)
/dialInSecurityProfiles(3.0 onwards)
/dialInSecurityProfiles/<dial in security profile id> (3.0 onwards)
`/dialTransforms`
`/dialTransforms/<dial transform id>`
`/directorySearchLocations`
`/directorySearchLocations/<directory search location id>`
`/dtmfProfiles`
`/dtmfProfiles/<dtmf profile id>`
`/forwardingDialPlanRules`
`/forwardingDialPlanRules/<forwarding dial plan rule id>`
`/inboundDialPlanRules`
`/inboundDialPlanRules/<inbound dial plan rule id>`
`/ivrs`
`/ivrs/<ivr id>`
`/ivrBrandingProfiles`
`/ivrBrandingProfiles/<ivr branding profile id>`
/layoutTemplates
/layoutTemplates/<layout template id>
/layoutTemplates/<layout template id>/template (2.8 onwards)
`/ldapMappings`
`/ldapMapping/<ldap mapping id>`
`/ldapServers`
`/ldapServers/<ldap server id>`
`/ldapSources`
`/ldapSources/<ldap source id>`
`/ldapSyncs`
`/ldapSyncs/<ldap sync id>`
/ldapUserCoSpaceTemplateSources(2.9 onwards)
/ldapUserCoSpaceTemplateSources/<ldap user coSpace template source id>(2.9 onwards)
`/outboundDialPlanRules`
`/outboundDialPlanRules/<outbound dial plan rule id>`
`/participants`
`/participants/<participantId>`
`/participants/<participantId>/callLegs`
/recorders (3.0 removed)
/recorders/<recorder id> (3.0 removed)
/recorders/<recorder id>/status (2.2 onwards) (3.0 removed)
/streamers (2.1 onwards) (3.0 removed)
/streamers/<streamer id> (2.1 onwards) (3.0 removed)
/streamers/<streamer id>/status (2.2 onwards) (3.0 removed)
`/system/alarms`
`/system/cdrReceiver (deprecated)`
`/system/cdrReceivers`
`/system/cdrReceivers/<CDR receiver id>`
`/system/configuration/cluster`
`/system/configuration/xmpp`
`/system/database`
`/system/diagnostics`
`/system/diagnostics/<diagnostics id>`
`/system/diagnostics/<diagnostics id>/contents`
`/system/licensing (2.0 onwards)`
`/system/load (2.1 onwards)`
`/system/MPLicenseUsage (2.6 onwards)`
`/system/multipartyLicensing (2.0 onwards)`
`/system/multipartyLicensing/activePersonalLicenses(2.0 onwards)`
`/system/profiles`
`/system/status`
`/tenantGroups`
`/tenantGroups/<tenant group id>`
`/tenants`
`/tenants/<tenant id>`
`/tenants/<tenant id>/effectiveWebBridgeProfile (3.0 onwards)`
`/turnServers`
`/turnServers/<turn server id>`
`/turnServers/<turn server id>/status`
/uriUsageQuery (2.3 onwards)
`/users`
`/users/<user id>`
`/users/<user id>/usercoSpaces`
/users/<user id>/userCoSpaceTemplates (2.9 onwards)
/users/<user id>/userCoSpaceTemplates/<user coSpace Template id>(2.9 onwards)
`/userProfiles`
`/userProfiles/<user profile id>`
`/webBridges`
`/webBridges/<web bridge id>`
`/webBridges/<web bridge id>/status (2.2 onwards)`
`/webBridges/<web bridge id>/updateCustomization`
/webBridgeProfiles(3.0 onwards)
/webBridgeProfiles/<web bridge profile id> (3.0 onwards)
/webBridges/<web bridge id>/effectiveWebBridgeProfile
(3.0 onwards)
In each case, the top level plural term sits above potentially many individual object nodes; these individual object nodes are identified by an <ID> which is a GUID, typically. For example, if there are 100 coSpaces configured on an Meeting Server, conceptually there would be 100 nodes directly beneath `/coSpaces` in the hierarchy.
## Accessing the API
The API uses HTTPS as a transport mechanism.
---
Note: The time taken for APIrequests can vary depending upon factors, including but not limited
to, the request type, number of outstanding requests, database size, server loading, latency
between API client and the Call Bridge receiving APIrequests, and latency between the Call
Bridge receiving the APIrequest and the primary database. We recommend that when
developing applications, you test API performance on a representative system.
---
### Configuration Settings
To use the API, you need to connect via HTTPS via the same TCP ports as you would use to access the Web Admin Interface – typically port 443; that is, they use the same interface.
You also need to configure a username and password: you must provide these credentials in order to use the API. Set them using the MMP command `user add <username> (admin|crypto|audit|appadmin|api)`. This command prompts for the user’s password; see the [MMP Command Reference](https://www.cisco.com/c/en/us/support/conferencing/meeting-server/products-programming-reference-guides-list.html) for details.
### Authentication
The API user supplies a shared secret username and password to the Meeting Server configured with the same username and password. The username and password are set in the MMP command line.
While the authentication credentials are sent in essentially plain text within the HTTP traffic, by using HTTPS the traffic itself cannot be read by an external party.
### API access on the web interface
To simplify using the API without the need for third-party applications, version 2.9 introduces a
user interface for the API that can be accessed via the Configuration tab of the Meeting Server
web interface.
---
Note: If you wish to delete any configured API objects, select Allow delete on the right-hand side
of the screen. By default deletion is disallowed and Require delete confirmation is checked to
help prevent unintentional deletions.
---
### Tools to Use
Suitable tools to access and update the API include:
* [Firefox Poster](https://addons.mozilla.org/en-US/firefox/addon/poster/)
* [Postman](https://www.getpostman.com) (OS X, Windows, Linux, and Chrome)
* [Paw](https://paw.cloud) (OS X)
* [Insomnia](https://insomnia.rest) (OS X, Windows, and Linux)
## API Methods
There are four methods:
* [GET](#get) is used for retrieval of existing information
* [POST](#post) is used to create new objects in the hierarchy
* [PUT](#put) is used to modify an existing object
* [DELETE](#delete) is used to destroy an object in the tree
These methods are described in more detail below.
### URL format
For the purposes of addressing or creating individual objects, the URL format mirrors the conceptual hierarchy of objects, with some additional preceding tags in order to identify that the request is for the API. By way of example, to retrieve information on API object `/calls/dbfca0dd-dbe1-43bb-b101-beb9a7ef35f4` it would be necessary to issue:
`GET /api/v1/calls/dbfca0dd-dbe1-43bb-b101-beb9a7ef35f4 HTTP/1.1`
Specifically, at the top level, including `/api` means that the on-board HTTP server process can distinguish this HTTP method from a normal browser method, and including `v1` means the API handler knows that the request is being made by an object that understands version 1 of the API.
If an API method is successful, it yields a “200 OK” response from the Meeting Server. If an error occurs, the Meeting Server responses with a 4xx or 5xx HTTP status code.
A 503 (“Service Unavailable”) status code is returned for API calls unable to be serviced due to a temporary “busy” condition on the Meeting Server – this can be used as an indication to the requestor that it would be useful to re-attempt the same method later.
Equally, a request supplying a <coSpace id> which does not correspond to a valid coSpace object yields “404 Not Found”.
For 4xx and 5xx error cases, extended error information may be returned as “text/xml” body data, for example:
`<failureDetails><coSpaceDoesNotExist/></failureDetails>`
More generally, such a response consists of a “failureDetails” section and a list of errors; in the above case a method was attempted using a coSpace ID that did not correspond to an active coSpace. The possible failure reasons are described in the section, [Failure Reasons](failreason).
### GET Methods
<a name="get"></a>
As mentioned above, GET methods allow retrieval of information about existing API accessible objects, and are used at two levels: Collections level and Individual object level.
#### Collections level
If the GET method is performed at the Collections level (the pluralized noun: “calls”, “coSpaces” etc.) then some number of matching child nodes will be retrieved. By design this is not guaranteed to be the entire list, but the total number of objects of that type present in the Meeting Server can be learnt via this mechanism.
In order to retrieve just specific items, most GET methods at the Collections level allow the use of a filter expression. The idea here is that the interface of a management tool would initially present the API user with the summed count of coSpaces (for example), basic details on the first “N” coSpaces (e.g. their names) and a filter box which the human user can use to search for the specific coSpace(s) of interest.
With no other additional parameters, a GET method at the Collections level will return items from the start of the Meeting Server's notional complete list. By comparing the number of items returned with the "total" value, it is straightforward to determine whether all elements have been returned (if the number of elements returned is equal to the "total" value).
#### Using limit and offset at the Collections level
It is possible to restrict the number of elements returned to a limit chosen by the requestor, by including a "limit=<limitValue>" in the API request. This guarantees that no more than the specified "limitValue" number of elements will be returned - the Meeting Server will have its own limit in these cases too, and therefore the number of elements returned will be the lower of any supplied "limitValue" and the Meeting Server's own limit.
In order to retrieve elements other than the first "n" on the Meeting Server's notional list, it is also possible to supply an "offset=<offsetValue>" in the API request. This causes the Meeting Server to return elements which start at the specified position in its list, skipping the first "offsetValue" number of elements. If "offsetValue" is greater than the number of objects of that type, then no elements will be returned.
---
**Note:** The offset value should not be viewed as a general mechanism for retrieving a large complete list - sequential retrievals of one "page" of data followed by a second "page" will not necessarily be operating on the same complete list if any objects have been deleted or added in the interval between these methods.
---
The expectation is that, for each request and response, the requestor will keep track of the offset and limit values used, and combine this knowledge with the number of elements returned in the response and the "total" indicated by the Meeting Server. If the "offsetValue" supplied by the requestor plus the number of elements returned is less than the "total" value indicated in the response, the requestor then knows that there are more values present. The following table shows some examples:
<table>
<tr>
<th>Requestor offset</th>
<th>Requestor limit</th>
<th>XML Response</th>
<th>Meaning</th>
</tr>
<tr>
<td>not supplied</td>
<td>not supplied</td>
<td></td>
<td>All coSpaces (0 – 6) present in response</td>
</tr>
<tr>
<td>not supplied</td>
<td>1</td>
<td></td>
<td>First coSpace present in response</td>
</tr>
<tr>
<td>4</td>
<td>10</td>
<td></td>
<td>coSpaces 4 - 6 present in response</td>
</tr>
<tr>
<td>20</td>
<td>10</td>
<td></td>
<td>coSpaces 20 - 27 present in response. (The Meeting Server limits its response to 8 entries despite the requestor allowing up to 10.)</td>
</tr>
</table>
#### Individual object level
If the GET method is performed at the Individual object level, full information about just that one object will be returned. For example, after the unique ID of a coSpace has been learnt via a (potentially filtered) GET of the `/coSpaces` node, a subsequent GET of the `/coSpaces/<coSpace id>` node would return expanded information about just that one coSpace, for example how many members it has, and when it was last activated.
#### HTTP specifics
GET methods contain the complete node location and any parameters specific to the retrieval being performed in the URI supplied by the API user. For example, to retrieve basic information on the first “N” coSpaces, the URI would be:
`/api/v1/coSpaces`
whereas to list just those whose name includes “sales”, the GET would be performed on:
`/api/v1/coSpaces?filter=sales`
If a GET method has been successful and yields a “200 OK” response, the Meeting Server returns the retrieved information as “text/xml” body data.
#### How GET methods are detailed in this document
For each GET method at the Collections level the following information is provided:
* The node it operates on
* A table of form parameters, such as filter, offset and limit mentioned above, some of which may be optional. Mandatory parameters are marked with an asterisk (*)
* A table showing the returned information
Both tables show the format of the parameter (e.g. `ID` or `string`) or the possible values (e.g. `true`|`false`)
For each GET method at the Individual level the following information is provided:
* The node it operates on
* A table showing the returned information
The form parameters are those for the Collections level, unless otherwise indicated.
### POST Methods
<a id="post"></a>
POST methods create new objects; for example, to create a new configured coSpace or dial plan rule. Using a POST method to create a new call leg associated with a coSpace is the way to make a new outbound SIP connection.
#### HTTP specifics
Most POST methods require some parameters to be supplied: for example, creation of a coSpace requires the new coSpace’s name to be specified, and a new call leg can only be created if the remote party’s address is known. Such parameters must be supplied by the initiator of the POST method via the standard HTTP “x-www-form- urlencoded” format, as used by “\<form\>” elements in an HTML document.
If a POST method has been successful in adding a new object to the hierarchy, that object’s id, and its position within the hierarchy are returned in the “Location” field of the response.
#### How POST methods are detailed in this document
For each POST method the following information is provided:
* The node it operates on
* A table of form parameters, some of which may be optional. Mandatory parameters are marked with an asterisk (*)
* The format of each parameter (e.g. `ID` or `string`) or the possible values (e.g. `true`|`false`). If appropriate the default value of a parameter (the value used if you do not specify a parameter) is shown in **bold** (e.g. `true`|`false`).
### PUT Methods
<a name="put"></a>
PUT methods modify existing objects; for example, changing the name of a coSpace, muting a specific call leg or changing the layout.
In general, when using PUT in an object:
* omit a parameter to leave its value unchanged
* use a parameter with a new value to change to this value. Supply an empty value to unset a value. For example, to remove a tenant association from a coSpace, modify that coSpace with a parameter set including “tenant=”.
#### HTTP specifics
Parameters for a request must be supplied in “x-www-form-urlencoded” format.
#### How PUT methods are detailed in this document
Each PUT method is in the same section as the POST method for the same object e.g. creating and modifying a coSpace are dealt with together. Form parameters for modifying an object (PUT) are only noted if they differ from the POST method; for example, for callLegs.
### DELETE Methods
<a name="delete"></a>
A DELETE method removes an individual object from the hierarchy; for example, disconnecting a call leg or disassociating a user from a coSpace so that the user is no longer a member.
Therefore the DELETE method is typically performed at the Individual level e.g. `DELETE on /api/v1/coSpace/<id>/accessMethods/<id>`
The object’s ID is known either from a previous retrieval (GET) method at the Collections level or from the “Location” field in the response to a previous creation (PUT) method. (coSpace can be deleted at the Collections level.)
If the object is removed successfully, the Meeting Server sends a “200 OK” response.
Because of the relative simplicity of this method, it is not detailed elsewhere in this document – with the exception of deleting chat messages.
### Failure Reasons
<a name="failreason"></a>
The following "failureDetails" codes can be returned by the API for any of the above methods, in the form in response to a user error:
`<failureDetails><tenantDoesNotExist /></failureDetails>`
<table>
<tr>
<th>Reason code</th>
<th>Description</th>
</tr>
<tr>
<td>accessMethodDoesNotExist</td>
<td>You tried to modify or remove an accessMethod using an ID that did not correspond to a valid access method</td>
</tr>
<tr>
<td>callBrandingProfileDoesNotExist</td>
<td>You tried to modify or remove a call branding profile using an ID that did not correspond to a valid call branding profile</td>
</tr>
<tr>
<td>callBridgeDoesNotExist</td>
<td>You tried to modify or remove a configured clustered Call Bridge using an ID that did not correspond to a valid clustered Call Bridge</td>
</tr>
<tr>
<td>callBridgeGroupDoesNotExist</td>
<td>You tried to modify, remove or use a Call Bridge group using an ID that did not correspond to a valid Call Bridge group (from version 2.1).</td>
</tr>
<tr>
<td>callBridgeGroupUnavailable</td>
<td>You tried to create a participant on a Call Bridge Group that is unavailable or could not accept the call (from version 2.2).</td>
</tr>
<tr>
<td>callBridgeUnavailable</td>
<td>You tried to create a participant on a Call Bridge that is unavailable or could not accept the call (from version 2.2).</td>
</tr>
<tr>
<td>callDoesNotExist</td>
<td>You tried to perform a method on a call object using an ID that did not correspond to a currently active call</td>
</tr>
<tr>
<td>callRecordingCannotBeModified</td>
<td>You tried to start/stop recording a call that cannot be modified. Present from R1.9</td>
</tr>
<tr>
<td>callStreamingCannotBeModified</td>
<td>You tried to start/stop streaming a call that cannot be modified. Present from v 2.1</td>
</tr>
<tr>
<td>callLegCannotBeDeleted</td>
<td>You tried to delete a call leg that can't be deleted. Present from R1.8</td>
</tr>
<tr>
<td>callLegDoesNotExist</td>
<td>You tried to perform a method on a call leg object using an ID that did not correspond to a currently active call leg</td>
</tr>
<tr>
<td>callLegProfileDoesNotExist</td>
<td>You tried to modify or remove a callLegProfile using an ID that did not correspond to a valid call leg profile</td>
</tr>
<tr>
<td>callProfileDoesNotExist</td>
<td>You tried to modify or remove a callProfile using an ID that is not valid</td>
</tr>
<tr>
<td>cdrReceiverDoesNotExist</td>
<td>You tried to modify or remove a CDR receiver using an ID that did not correspond to a valid CDR receiver. Present from R1.8</td>
</tr>
<tr>
<td>compatibilityProfileDoesNotExist</td>
<td>You tried to modify or remove a compatibility profile using an ID that did not correspond to a valid compatibility profile.</td>
</tr>
<tr>
<td>coSpaceAccessMethodTemplateDoesNotExist</td>
<td>You tried to modify, remove or retrieve a coSpace access method template using an ID that did not correspond to a valid coSpace access method template on the system (from version 2.9).</td>
</tr>
<tr>
<td>coSpaceDoesNotExist</td>
<td>You tried to modify or remove a coSpace using an ID that did not correspond to a valid coSpace on the system</td>
</tr>
<tr>
<td>coSpaceTemplateDoesNotExist</td>
<td>You tried to modify, remove or retrieve a coSpace template using an ID that did not correspond to a valid coSpace tem-plate on the system (from version 2.9).</td>
</tr>
<tr>
<td>coSpaceUserDoesNotExist</td>
<td>You tried to modify or remove a coSpace user using an ID that did not correspond to a valid coSpace user.</td>
</tr>
<tr>
<td>databaseNotReady</td>
<td>You tried a method (e.g. initiation of an LDAP sync method) before the database was ready</td>
</tr>
<tr>
<td>dialInSecurityProfileDoesNotExist</td>
<td>You tried to modify, remove, or retrieve a dial-in security pro-file using an ID that did not correspond to a valid dial-in secur-ity profile. (3.0 onwards)</td>
</tr>
<tr>
<td>directorySearchLocationDoesNotExist</td>
<td>You tried to reference, modify or remove a directory search location using an ID that did not correspond to a valid directory search location. Present from R1.8</td>
</tr>
<tr>
<td>dtmfProfileDoesNotExist</td>
<td>You tried to reference, modify or remove a DTMF profile using an ID that did not correspond to a valid DTMF profile</td>
</tr>
<tr>
<td>duplicateCallBridgeName</td>
<td>You tried to create or modify a clustered Call Bridge to use a name that would clash with an existing configured clustered Call Bridge</td>
</tr>
<tr>
<td>duplicateCoSpaceId</td>
<td>You tried to create or modify a coSpace call ID to use a call ID that clashed with one used by another coSpace</td>
</tr>
<tr>
<td>duplicateCoSpaceUri</td>
<td>You tried to create or modify a coSpace to use a URI that clashed with one that corresponds to another coSpace. (Two coSpaces can't share the same URI, because the Meeting Server must be able to uniquely resolve an incoming call to a coSpace URI)</td>
</tr>
<tr>
<td>duplicateCoSpaceIdPasscode</td>
<td>You tried to modify a coSpace, or create or modify a coSpace access method, using a call ID/passcode combination that clashed with another call ID/passcode that is already used by that coSpace or one of its access methods.</td>
</tr>
<tr>
<td>duplicateCoSpaceUriPasscode</td>
<td>You tried to modify a coSpace, or create or modify a coSpace access method, using a URI/passcode combination that clashed with URI/passcode combination that is already used by that coSpace or one of its access methods.</td>
</tr>
<tr>
<td>duplicateUserCoSpaceTemplate</td>
<td>You tried to assign the same coSpace template to a user for a second time (from version 2.9).</td>
</tr>
<tr>
<td>duplicateSipEndpointUri</td>
<td>You tried to create or modify a registered SIP endpoint, using a URI that clashed with one that is already used by another registered SIP endpoint.</td>
</tr>
<tr>
<td>forwardingDialPlanRuleDoesNotExist</td>
<td>You tried to modify or remove an forwarding dial plan rule using an ID that did not correspond to a valid forwarding dial plan rule</td>
</tr>
<tr>
<td>inboundDialPlanRuleDoesNotExist</td>
<td>You tried to modify or remove an inbound dial plan rule using an ID that did not correspond to a valid inbound dial plan rule</td>
</tr>
<tr>
<td>inboundDialPlanRuleUriConflict</td>
<td>You tried to make modifications to an inbound dial plan rule which would have caused a URI conflict. For example, this can happen if you try to add a rule which matches multiple tenants and more than one tenant has a coSpace with the same URI</td>
</tr>
<tr>
<td>invalidOperation</td>
<td>You tried an operation which isn't supported; for example, you attempted to POST to /api/v1/system/profiles or issue a DELETE for a configured user generated from an LDAP sync</td>
</tr>
<tr>
<td>invalidVersion</td>
<td>You attempted an operation with an invalid API version. Present from R1.8</td>
</tr>
<tr>
<td>ivrBrandingProfileDoesNotExist</td>
<td>You tried to modify or remove an IVR branding profile object using an ID that did not correspond to a valid IVR branding profile on the system</td>
</tr>
<tr>
<td>ivrDoesNotExist</td>
<td>You tried to modify or remove an IVR object using an ID that did not correspond to a valid IVR on the system</td>
</tr>
<tr>
<td>ivrUriConflict</td>
<td>You tried to make modifications to an IVR object which would have caused a URI conflict</td>
</tr>
<tr>
<td>layoutTemplateDoesNotExist</td>
<td>You tried to modify, remove or retrieve a layout template using an ID that did not correspond to a valid layout template on the system (from version 2.8).</td>
</tr>
<tr>
<td>layoutTemplateDoesNotExist</td>
<td>You tried to modify, remove or retrieve a layout template using an ID that did not correspond to a valid layout template on the system (from version 2.8).</td>
</tr>
<tr>
<td>layoutTemplateDescriptionTooLong</td>
<td>You tried to set a layout template description that exceeds the allowed size (from version 2.8).</td>
</tr>
<tr>
<td>ldapMappingDoesNotExist</td>
<td>You tried to modify or remove an LDAP mapping using an ID that did not correspond to a valid LDAP mapping</td>
</tr>
<tr>
<td>ldapServerDoesNotExist</td>
<td>You tried to modify or remove an LDAP server using an ID that did not correspond to a valid LDAP server</td>
</tr>
<tr>
<td>ldapSourceDoesNotExist</td>
<td>You tried to modify or remove an LDAP source using an ID that did not correspond to a valid LDAP source</td>
</tr>
<tr>
<td>ldapSyncCannotBeCancelled</td>
<td>You tried to cancel an LDAP synchronization that has either started or completed – only LDAP synchronization methods that have not started yet can be cancelled</td>
</tr>
<tr>
<td>ldapUserCoSpaceTemplateSourceDoesNotExist</td>
<td>You tried to remove or retrieve using an ID that did not cor-respond to an existing LDAP user coSpace template source entry (from version 2.9).</td>
</tr>
<tr>
<td>ldapSyncDoesNotExist</td>
<td>You tried to query or cancel an LDAP synchronization with an ID that did not correspond to a valid LDAP synchronization</td>
</tr>
<tr>
<td>ldapUserCoSpaceTemplateSourceDoesNotExist</td>
<td>You tried to remove or retrieve using an ID that did not correspond to an existing LDAP user coSpace template source entry (from version 2.9).</td>
</tr>
<tr>
<td>loadBalancingDisabled</td>
<td>You tried to create a participant in a Call Bridge Group with load balancing for outgoing calls disabled (from version 2.2).</td>
</tr>
<tr>
<td>messageDoesNotExist</td>
<td>You tried to remove a coSpace message using an ID that did not correspond to a valid coSpace message</td>
</tr>
<tr>
<td>outboundDialPlanRuleDoesNotExist</td>
<td>You tried to modify or remove an outbound dial plan rule using an ID that did not correspond to a valid outbound dial plan rule</td>
</tr>
<tr>
<td>parameterError</td>
<td>One or more parameters in a request were found to be invalid. Supporting parameter and error values give more detail about the failure</td>
</tr>
<tr>
<tr>
<td>participantCannotBeDeleted</td>
<td>You tried to delete a participant that could not be deleted, for instance a remotely-hosted participant.</td>
</tr>
<tr>
<td>participantCannotBeModified</td>
<td>You tried to modify a participant that could not be modified, for instance a participant hosted on a remote deployment.</td>
</tr>
<tr>
<td>participantLimitReached</td>
<td>You tried to add a new participant beyond the maximum number allowed for the call</td>
</tr>
<tr>
<td>passcodeTooShort</td>
<td>You tried to set a passcode to a coSpace or a coSpace access method but its length is not compliant with the min-imum allowed passcode length as specified in the effective dial-in security profile. (3.0 onwards)</td>
</tr>
<tr>
<td>recorderDoesNotExist</td>
<td>You tried to modify or remove a recorder using an ID that did not correspond to a valid recorder. (From version 1.9)</td>
</tr>
<tr>
<td>recordingNotAllowedByLicensing</td>
<td>You tried to start recording without having the correct license. (Previously recordingLimitReached) (3.0 onwards)</td>
</tr>
<tr>
<td>recordingLimitReached</td>
<td>You tried to start recording a call beyond the maximum number allowed(TBD).</td>
</tr>
<tr>
<td>sipEndpointDoesNotExist</td>
<td>You tried to modify or remove a registered sip endpoint using an ID that did not correspond to a valid endpoint.<td>
</tr>
<tr>
<td>streamerDoesNotExist</td>
<td>You tried to modify or remove a streamer using an ID that did not correspond to a valid streamer (from version 2.1).</td>
</tr>
<tr>
<td>streamingNotAllowedByLicensing</td>
<td>You tried to start streaming without having the correct license. (Previously streamingLimitReached) (3.0 onwards)</td>
</tr>
<tr>
<td>streamingLimitReached</td>
<td>You tried to start streaming a call beyond the maximum num-ber allowed (from version 2.1 TBD).</td>
</tr>
<tr>
<td>tenantDoesNotExist</td>
<td>You tried to modify or remove a tenant using an ID that did not correspond to a valid tenant</td>
</tr>
<tr>
<td>tenantGroupCoSpaceIdConflict</td>
<td>Your request to remove or use a tenant group would have resulted in a coSpace ID conflict. Present from R1.8</td>
</tr>
<tr>
<td>tenantGroupDoesNotExist</td>
<td>You tried to modify, remove or use a tenant group that does not exist. Present from R1.8</td>
</tr>
<tr>
<td>tenantParticipantLimitReached</td>
<td>You tried to add a new participant beyond the maximum number allowed for the owning tenant</td>
</tr>
<tr>
<td>tooManyCdrReceivers</td>
<td>You tried to add a new CDR receiver when the maximum number were already present. R1.8 supports up to 2 CDR receivers</td>
</tr>
<tr>
<td>tooManyLdapSyncs</td>
<td>A method to create a new LDAP synchronization method failed. Try again later</td>
</tr>
<tr>
<td>unrecognizedObject</td>
<td>There are elements in the URI you are accessing that are not recognized; e.g, you tried to perform a GET on /api/v1/system/profile rather than (the correct) /api/v1/system/profiles</td>
</tr>
<tr>
<td>userCoSpaceTemplateDeletionProhibited</td>
<td>You tried to withdraw an auto-generated coSpace template from a user and this is not allowed (from version 2.9).</td>
</tr>
<tr>
<td>userCoSpaceTemplateDoesNotExist</td>
<td>You tried to modify, remove or retrieve a user coSpace tem-plate using an ID that did not correspond to a valid user coSpace template for that user (from version 2.9).</td>
</tr>
<tr>
<td>userDoesNotExist</td>
<td>You tried to modify or remove a user using an ID that did not correspond to a valid user</td>
</tr>
<tr>
<td>userProfileDoesNotExist</td>
<td>You tried to modify a user profile using an ID that did not correspond to a valid user profile</td>
</tr>
</table>
## Example Requests and Responses for Specific Methods [/sample]
### Retrieval of Current Active Calls [GET /calls]
As described [above](#get), retrieval methods using GET involve no body content posted by the retriever. If the request is valid, the Meeting Server returns XML response data.
+ Request
+ Headers
Authorization: Basic Ym9iOmJ1aWxkZXI=
+ Response 200 (text/xml)
+ Headers
Connection: close
+ Body
<?xml version="1.0"?>
<calls total="1">
<call id="527089d6-6581-4331-8417-971c05c9e274">
<name>Sales coSpace</name>
<coSpace>2dcf2b7a-3410-4066-b638-46273698d469</coSpace>
</call>
</calls>
### Creating a New Call Leg SIP dial out to 10.1.144.129 [POST /callLegs]
As described above, any parameters needed for the creation method (in this case, the address of the remote party), need to be supplied by the issuer as form data. If the request is successful, details about the new object are returned by the Meeting Server in the “Location” header field.
+ Request
+ Headers
Authorization: Basic Ym9iOmJ1aWxkZXI=
Content-Type: application/x-www-form-urlencoded
+ Body
remoteParty=10.1.144.129
+ Response 200
+ Headers
Location: /api/v1/callLegs/5a3b907a-7641-42fb-ae8c-b3424a3e923f
Connection: close
### Instantiating a new call and connecting a participant to it [/sample1]
As described above, any parameters needed for the creation method (in this case, the address of the remote party), need to be supplied by the issuer as form data. If the request is successful, details about the new object are returned by the Meeting Server in the “Location” header field.
## Use a filtered coSpace enumeration to find "Development Team" [GET /calls]
As described above, any parameters needed for the creation method (in this case, the address of the remote party), need to be supplied by the issuer as form data. If the request is successful, details about the new object are returned by the Meeting Server in the “Location” header field.
+ Request
+ Headers
Authorization: Basic Ym9iOmJ1aWxkZXI=
+ Response 200 (XML)
+ Headers
Connection: close
+ Body
<?xml version="1.0"?>
<coSpaces total="1">
<coSpace id="581caae0-420a-43df-9a9e-f690c70e12d3">
<name>DevelopmentTeam</name>
<autoGenerated>false</autoGenerated>
<uri>dev_team</uri>
</coSpace>
</coSpaces>
## Instantiate a call from the coSpace [POST /calls]
Matching coSpace `581caae0-420a-43df-9a9e-f690c70e12d3` found in enumeration response, now use it to instantiate a call from the coSpace
+ Request
+ Headers
Authorization: Basic Ym9iOmJ1aWxkZXI=
+ Body
coSpace=581caae0-420a-43df-9a9e-f690c70e12d3
+ Response 200 (XML)
+ Headers
Connection: close
+ Body
Location: /api/v1/calls/8867d8f1-0918-4653-b41e-7341200e277a
Connection: close
## Create a participant [POST /calls]
Create participant as a call out from the newly-instantiated call `/api/v1/participants/2671a77d-4bd5-4bf2-8ed6-f14afd80c2ac`.
+ Request
+ Headers
Authorization: Basic Ym9iOmJ1aWxkZXI=
+ Body
POST /api/v1/calls/8867d8f1-0918-4653-b41e-7341200e277a/participants
HTTP/1.1\r\n
Host: 127.0.0.1\r\n
Content-Type: www-formurl-encoded\r\n
Content-Length: 33\r\n\r\n
+ Response 200 (XML)
+ Headers
Connection: close
+ Body
HTTP/1.1 200 OK\r\n
Location: /api/v1/participants/2671a77d-4bd5-4bf2-8ed6-f14afd80c2ac\r\n
Connection: close\r\n\r\n
# Group coSpace Related Methods
---
**Note:** From release 1.9, coSpace has been renamed as space. Although the Cisco Meeting App and other Cisco Meeting Server guides refer to
"spaces" rather than "coSpaces", the API still uses `/coSpace` objects. The Web Admin interface has been changed to refer to "spaces".
---
This chapter details the API methods related to management of coSpaces. The chapter covers:
* retrieving coSpaces
* creating and modifying a coSpace
* retrieving detailed information about a single coSpace
* retrieving the members of a coSpace
* adding and modifying a coSpace member
* posting to the message board of a coSpace
* deleting messages from a coSpace message board
* retrieving coSpace access methods
* creating and modifying coSpace access methods
* calling out from a coSpace
* bulk creating, updating, and deleting coSpaces
* coSpace diagnostics
<a name="retrievingspace"></a>
## Retrieving coSpaces [GET /coSpaces/{?offset,limit,filter,tenantFilter,callLegProfileFilter}]
GET method on the `/coSpaces` node
The response includes the total count of the number of coSpaces present which match the filter if provided, irrespective of the number returned within the response. (With no filter, this value is the total number of configured coSpaces).
TODO: Response is structured as a top-level \<coSpaces total=”N”\> tag with potentially multiple \<coSpace\> elements within it.
<coSpace> elements follow the general form on the left.
<table>
<tr>
<th>Response elements</th>
<th>Type/Value</th>
<th>Description/Notes</th>
</tr>
<tr>
<td>coSpace id</td>
<td>ID</td>
<td>The “ID” value returned in the opening tag is a unique identifier for the coSpace, and can be used for future modify / delete / query methods on that coSpace</td>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>The human-readable name that will be shown on clients' UI for this coSpace</td>
</tr>
<tr>
<td>uri</td>
<td>String</td>
<td>The URI that a SIP system would use to dial in to this coSpace</td>
</tr>
<tr>
<td>secondaryUri</td>
<td>String</td>
<td>The secondary URI for this coSpace – this provide the same functionality as the “uri” parameter, but allows more than one URI to be configured for a coSpace</td>
</tr>
<tr>
<td>callId</td>
<td>Number</td>
<td>The numeric ID that a user would enter at the IVR (or via a web client) to connect to this coSpace</td>
</tr>
<tr>
<td>tenant</td>
<td>ID</td>
<td>If provided, associates the specified call leg profile with this tenant</td>
</tr>
<tr>
<td>autoGenerated</td>
<td>boolean</td>
<td>Whether this coSpace has been added automatically or manually.
<ul>
<li>true - this coSpace has been added automatically as part of an LDAP sync operation. therefore it is not possible, to remove it except by modifying the parameters of the sync operation</li>
<li>false - this coSpace has been added either via an API method or by using Cisco Meeting App; it can be modified or removed via the API</li>
</ul>
</td>
</tr>
</table>
+ Parameters
+ offset (Number, optional)
An "offset" and "limit" can be supplied to retrieve coSpaces other than the first “page" in the notional list (see Section 4.1.2).
+ limit (Number, optional)
An "offset" and "limit" can be supplied to retrieve coSpaces other than the first “page" in the notional list (see Section 4.1.2).
+ filter (String, optional)
Supply “filter=`<String`>” in the URI to return just those coSpaces that match the filter
+ tenantFilter (ID, optional) - Supply tenantFilter=<tenant id> to return just those coSpaces associated with that tenant
+ callLegProfileFilter (ID, optional)
Supply callLegProfileFilter=`<call leg profile id>` to return just those coSpaces using that call leg profile
+ Request
+ Headers
Authorization: Basic Ym9iOmJ1aWxkZXI=
+ Response 200 (text/xml)
+ Body
<?xml version="1.0"?>
<coSpaces total="1">
<coSpace id="527089d6-6581-4331-8417-971c05c9e274">
<name>Sales coSpace</name>
</coSpace>
</coSpaces>
## Creating and Modifying a coSpace [POST /coSpaces]
* Creating: POST method to the `/coSpaces` node. If the coSpace was created successfully, a “200 OK” response is received, and the “Location” header contains the ID for the new coSpace
* Modifying: PUT method on a `/coSpaces/<coSpace id>` node
---
**Note:** You can also use this PUT to modify the values of a coSpace created in Cisco Meeting App. For example, the coSpace will have been created with the cdrTag of the user who created it but you can change that value with an API call. (This is unlike the cdrTag of an automatically generated coSpace, which cannot be updated with an API call).
---
<table>
<tr>
<th>Parameters</th>
<th>Type/Value</th>
<th>Description/Notes</th>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>The human-readable name that will be shown on clients’ UI for this coSpace</td>
</tr>
<tr>
<td>uri</td>
<td>String(URI user part)</td>
<td>The URI that a SIP system would use to dial in to this coSpace. (The URI 'user part' is the part before any '@' character in a full URI.)</td>
</tr>
<tr>
<td>secondaryUri</td>
<td>String(URI user part)</td>
<td>The secondary URI for this coSpace – this provides the same functionality as the “uri” parameter, but allows more than one URI to be configured for a coSpace. (The URI "user part" is the part before any '@' character in a full URI.)</td>
</tr>
<tr>
<td>callId</td>
<td>String</td>
<td>The numeric ID that a user would enter at the IVR (or via a web client) to connect to this coSpace</td>
</tr>
<tr>
<td>cdrTag</td>
<td>String</td>
<td>Up to 100 characters of free form text to identify this coSpace in a CDR; when a "callStart" CDR is generated for a call associated with this coSpace, this tag will be written (as "cdrTag") to the callStart CDR. See the Cisco Meeting Server CDR Reference for details. The cdrTag can be modified in a PUT method.</td>
</tr>
<tr>
<td>passcode</td>
<td>String</td>
<td>The security code for this coSpace</td>
</tr>
<tr>
<td>defaultLayout</td>
<td>allEqual|<br> speakerOnly|<br> telepresence|<br>stacked|<br>allEqualQuarters|<br>allEqualNinths|<br>allEqualSixteenths| <br>allEqualTwentyFifths|<br>onePlusFive|<br>onePlusSeven|<br>onePlusNine|<br> automatic|<br>onePlusN</td>
<td>The default layout to be used for new call legs in this coSpace. See Default layout options for the difference in naming between the API and the Web Admin interface</td>
</tr>
<tr>
<td>tenant</td>
<td>ID</td>
<td>If provided, associates the specified tenant with this coSpace</td>
</tr>
<tr>
<td>callLegProfile</td>
<td>ID</td>
<td>If provided, associates the specified call leg profile with this coSpace</td>
</tr>
<tr>
<td>callProfile</td>
<td>ID</td>
<td>If provided, associates the specified call profile with this coSpace</td>
</tr>