🚀 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.