# Search Rooms

## POST /v3/room/search

> Search rooms according to the specified criteria.

```json
{"openapi":"3.1.1","info":{"title":"Pod API","version":"20.17.1"},"servers":[{"url":"http://yourpodURL.symphony.com/pod"}],"paths":{"/v3/room/search":{"post":{"summary":"Search rooms according to the specified criteria.","parameters":[{"schema":{"type":"string"},"name":"sessionToken","description":"Session authentication token.","in":"header","required":true},{"schema":{"type":"integer"},"name":"skip","description":"No. of results to skip.\n","in":"query"},{"schema":{"type":"integer"},"name":"limit","description":"Max no. of results to return. If no value is provided, 50 is the default. Must be a positive\ninteger and must not exceed 100\n","in":"query","required":false},{"schema":{"type":"boolean","default":false},"name":"includeNonDiscoverable","description":"Whether the non discoverable rooms should be returned. false by default. Parameter introduced in sbe-25.5.0","in":"query","required":false}],"tags":["Streams"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RoomSearchResults"}}}},"400":{"description":"Client error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized: Invalid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden: Caller lacks necessary entitlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2RoomSearchCriteria"}}},"description":"The search query object.","required":true}}}},"components":{"schemas":{"V3RoomSearchResults":{"description":"A list of search results and counts per search parameter.","properties":{"count":{"description":"The total number of rooms matched by the search.","type":"integer","format":"int64"},"skip":{"description":"The number of skipped results.","type":"integer"},"limit":{"description":"The number of returned results.","type":"integer"},"query":{"$ref":"#/components/schemas/V2RoomSearchCriteria"},"rooms":{"description":"A list of rooms matched by the query.","type":"array","items":{"$ref":"#/components/schemas/V3RoomDetail"}},"facetedMatchCount":{"description":"Detailed counts of matched rooms per search criterion.","type":"array","items":{"$ref":"#/components/schemas/FacetedMatchCount"}}}},"V2RoomSearchCriteria":{"description":"Room Query Object. Used to specify the parameters for room search.","allOf":[{"$ref":"#/components/schemas/RoomSearchCriteria"},{"type":"object","properties":{"subType":{"description":"Restrict the search to the specific room subtype. Valid values are: EMAIL","type":"string"}}}]},"RoomSearchCriteria":{"description":"Room Query Object. Used to specify the parameters for room search.","properties":{"query":{"description":"The search query. Matches the room name and description.","type":"string"},"labels":{"description":"A list of room tag labels whose values will be queried.","type":"array","items":{"type":"string"}},"searchFields":{"description":"The room fields on which to search. Parameter introduced in sbe-25.10.0","type":"array","items":{"type":"string"}},"active":{"description":"Restrict the search to active/inactive rooms. If unspecified, search all rooms.","type":"boolean"},"private":{"description":"Restrict the search to private rooms. If unspecified, search all rooms.","type":"boolean"},"owner":{"$ref":"#/components/schemas/UserId"},"creator":{"$ref":"#/components/schemas/UserId"},"member":{"$ref":"#/components/schemas/UserId"},"sortOrder":{"description":"Sort algorithm to be used. Supports two values: \"BASIC\" (legacy algorithm)\nand \"RELEVANCE\" (enhanced algorithm).\n","type":"string","enum":["BASIC","RELEVANCE"]}},"required":["query"]},"UserId":{"type":"object","properties":{"id":{"type":"integer","format":"int64"}}},"V3RoomDetail":{"type":"object","properties":{"roomAttributes":{"$ref":"#/components/schemas/V3RoomAttributes"},"roomSystemInfo":{"$ref":"#/components/schemas/RoomSystemInfo"},"groups":{"description":"List of groups (aka SDLs) that were added to the room.","type":"array","items":{"$ref":"#/components/schemas/GroupItem"}}}},"V3RoomAttributes":{"type":"object","properties":{"name":{"type":"string","description":"Room name."},"keywords":{"type":"array","description":"Keywords for search to use to find this room","items":{"$ref":"#/components/schemas/RoomTag"}},"description":{"type":"string","description":"Room description."},"membersCanInvite":{"type":"boolean","description":"If true, any chatroom participant can add new participants. If false, only owners can add new participants."},"discoverable":{"type":"boolean","description":"If true, this chatroom (name, description and messages) can be searched and listed by non-participants. If false, only participants can search this room."},"public":{"type":"boolean","description":"If true, this is a public chatroom. IF false, a private chatroom."},"readOnly":{"type":"boolean","description":"If true, only stream owners can send messages."},"copyProtected":{"type":"boolean","description":"If true, clients disable the clipboard copy for content in this stream."},"crossPod":{"type":"boolean","description":"If true, this room is a cross pod room"},"viewHistory":{"type":"boolean","description":"If true, new members can view the room chat history of the room."},"multiLateralRoom":{"type":"boolean","description":"If true, this is a multi lateral room where we can find users belonging to more than 2 companies."},"scheduledMeeting":{"type":"boolean","description":"If true, this room is for a scheduled meeting."},"subType":{"type":"string","description":"This field is ignored when creating a new room as it was only used for email integration which is now sunset."},"pinnedMessageId":{"type":"string","description":"UrlSafe message id of the pinned message inside the room. To perform unpin operation, send an empty string."},"groupChat":{"type":"boolean","description":"If true, this room is a group chat. Note: this parameter is ignored for creating rooms. Since SBE 20.16."}}},"RoomTag":{"description":"Room Tag object. A key:value pair describing additional properties of the room.","properties":{"key":{"description":"A unique label of the Tag.","type":"string"},"value":{"description":"The value of this Tag's label.","type":"string"}},"required":["key","value"]},"RoomSystemInfo":{"type":"object","properties":{"id":{"type":"string"},"creationDate":{"type":"integer","format":"int64","description":"The datetime when the stream was originally created. Milliseconds since Jan 1 1970."},"createdByUserId":{"type":"integer","format":"int64"},"active":{"type":"boolean","description":"If false, no messages can be sent in this stream, and membership is locked."}}},"GroupItem":{"type":"object","properties":{"id":{"description":"The ID of the added group (aka SDL).","type":"integer","format":"int64"},"addedBy":{"description":"The user ID who added the group to the room.","type":"integer","format":"int64"}}},"FacetedMatchCount":{"description":"An object respresenting the result count of faceted search.","properties":{"facet":{"description":"The matched query.","type":"string"},"count":{"description":"The result count.","type":"integer"}}},"Error":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}}}
```

> #### 📘 Room Search Scope
>
> Room search is performed on the set of:
>
> * All rooms that the calling user is a member of (private or public, active or inactive)
> * All active public rooms
> * Private rooms that the calling user is not a member of, where the room is set to be visible in search, is active and the room does not contain any user with whom the calling user has an information barrier
>
> Note: visit [Overview](https://docs.developers.symphony.com/building-bots-on-symphony/datafeed/overview-of-streams) for an overview of streams.

> #### 🚧 Room Description Search
>
> The description is only searched for hashtags and cashtags containing the search query. For example if `query` were `foo` and the description of a room contained "foo", this room would not be returned in the search results; however, if the description contained "#foo", this room would be returned in the search results.