Search API
Find recipients SearchController#recipients
GET /api/v1/conversations/find_recipients
url:GET|/api/v1/conversations/find_recipients
GET /api/v1/search/recipients
url:GET|/api/v1/search/recipients
Find valid recipients (users, courses and groups) that the current user can send messages to. The /api/v1/search/recipients path is the preferred endpoint, /api/v1/conversations/find_recipients is deprecated.
Pagination is supported.
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
search | string |
Search terms used for matching users/courses/groups (e.g. “bob smith”). If multiple terms are given (separated via whitespace), only results matching all terms will be returned. |
|
context | string |
Limit the search to a particular course/group (e.g. “course_3” or “group_4”). |
|
exclude[] | string |
Array of ids to exclude from the search. These may be user ids or course/group ids prefixed with “course_” or “group_” respectively, e.g. exclude[]=1&exclude=2&exclude[]=course_3 |
|
type | string |
Limit the search just to users or contexts (groups/courses).
Allowed values: |
|
user_id | integer |
Search for a specific user id. This ignores the other above parameters, and will never return more than one result. |
|
from_conversation_id | integer |
When searching by user_id, only users that could be normally messaged by this user will be returned. This parameter allows you to specify a conversation that will be referenced for a shared context – if both the current user and the searched user are in the conversation, the user will be returned. This is used to start new side conversations. |
|
permissions[] | string |
Array of permission strings to be checked for each matched context (e.g. “send_messages”). This argument determines which permissions may be returned in the response; it won’t prevent contexts from being returned if they don’t grant the permission(s). |
API response field:
-
id
The unique identifier for the user/context. For groups/courses, the id is prefixed by “group_”/“course_” respectively.
-
name
The name of the context or short name of the user
-
full_name
Only set for users. The full name of the user
-
avatar_url
Avatar image url for the user/context
-
type
- “context”|“course”|“section”|“group”|“user”|null
-
Type of recipients to return, defaults to null (all). “context” encompasses “course”, “section” and “group”
-
types[]
Array of recipient types to return (see type above), e.g. types[]=user&types=course
-
user_count
Only set for contexts, indicates number of messageable users
-
common_courses
Only set for users. Hash of course ids and enrollment types for each course to show what they share with this user
-
common_groups
Only set for users. Hash of group ids and enrollment types for each group to show what they share with this user
-
permissions[]
Only set for contexts. Mapping of requested permissions that the context grants the current user, e.g. { send_messages: true }
Example Response:
[
{"id": "group_1", "name": "the group", "type": "context", "user_count": 3},
{"id": 2, "name": "greg", "full_name": "greg jones", "common_courses": {}, "common_groups": {"1": ["Member"]}}
]
List all courses SearchController#all_courses
GET /api/v1/search/all_courses
url:GET|/api/v1/search/all_courses
A paginated list of all courses visible in the public index
Request Parameters:
Parameter | Type | Description | |
---|---|---|---|
search | string |
Search terms used for matching users/courses/groups (e.g. “bob smith”). If multiple terms are given (separated via whitespace), only results matching all terms will be returned. |
|
public_only | boolean |
Only return courses with public content. Defaults to false. |
|
open_enrollment_only | boolean |
Only return courses that allow self enrollment. Defaults to false. |