🚀 Heads up: Our API Docs Have Moved!
We have relocated to Instructure Developer Documentation Portal. 🎉 Please update your bookmarks. This page will automatically redirect after July 1, 2026.

Search API

Find recipients SearchController#recipients

GET /api/v1/conversations/find_recipients

Scope: url:GET|/api/v1/conversations/find_recipients

GET /api/v1/search/recipients

Scope: 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, context

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

Scope: 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.