Community

Media

Search media by the given query parameters. If multiple options are provided, we will use a logical AND operation when searching!

get
Authorizations
Query parameters
titlestringOptional

Substring of the media title you want to search for.

min_sizeintegerOptional

Minimum size of the media in bytes.

max_sizeintegerOptional

Maximum size of the media in bytes.

start_datestring · dateOptional

Start of the creation date (inclusive). Format: YYYY-MM-DD.

end_datestring · dateOptional

End of the creation date (inclusive). Format: YYYY-MM-DD.

last_viewed_start_datestring · dateOptional

Start of the last viewed date (inclusive). Format: YYYY-MM-DD.

last_viewed_end_datestring · dateOptional

End of the last viewed date (inclusive). Format: YYYY-MM-DD.

last_viewed_by_student_start_datestring · dateOptional

Start of the last viewed by student date (inclusive). Format: YYYY-MM-DD.

last_viewed_by_student_end_datestring · dateOptional

End of the last viewed by student date (inclusive). Format: YYYY-MM-DD.

ownerstring · emailOptional

Email address of the owner of the media.

tagstringOptional

The full name of the tag, you want to list media objects for.

sourcestring · enumOptional

The source of the media you want to list media objects for.

Possible values:
pageintegerOptional

The page to retrieve. Default: 1.

Default: 1
per_pageinteger · max: 50Optional

The number of results per page. Default: 20, Max: 50.

Default: 20
Responses
200

The list of media objects that matched the given query.

application/json
Responseall of
get
GET /api/public/v1/media/search HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "media": [
    {
      "id": 1,
      "title": "text",
      "description": "text",
      "duration": 1,
      "created_at": "2025-08-25T07:31:11.261Z",
      "last_viewed": "2025-08-25",
      "last_viewed_by_student": "2025-08-25",
      "thumbnail_url": "text",
      "transcoding_status": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "size": 1,
      "source": "text",
      "embed_id": "text",
      "lti_launch_id": "text"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "total_count": 1
  }
}

Get a media by its id

get
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Responses
200

The media object that was requested.

application/json
get
GET /api/public/v1/media/{media_id} HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-08-25T07:31:11.261Z",
    "last_viewed": "2025-08-25",
    "last_viewed_by_student": "2025-08-25",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "size": 1,
    "source": "text",
    "embed_id": "text",
    "lti_launch_id": "text",
    "collection": {
      "id": 1,
      "name": "text",
      "type": "text",
      "permission": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "created_at": "2025-08-25T07:31:11.261Z",
      "course_id": 1
    }
  }
}

Deletes the specified media object and all related perspectives.

delete
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Responses
200

The media object that was deleted.

application/json
delete
DELETE /api/public/v1/media/{media_id} HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-08-25T07:31:11.261Z",
    "last_viewed": "2025-08-25",
    "last_viewed_by_student": "2025-08-25",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "size": 1,
    "source": "text",
    "embed_id": "text",
    "lti_launch_id": "text",
    "collection": {
      "id": 1,
      "name": "text",
      "type": "text",
      "permission": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "created_at": "2025-08-25T07:31:11.261Z",
      "course_id": 1
    }
  }
}

Get a list of courses which contains the media

get
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Responses
200

The list of courses that were requested.

application/json
get
GET /api/public/v1/media/{media_id}/courses HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "courses": [
    {
      "id": 1,
      "name": "text",
      "embedded_at": "2025-08-25T07:31:11.261Z"
    }
  ]
}

Adds a Media to a Course Collection for the given course_id. Returns the URL to LTI-launch the embedded media.

post
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Body

An object containing the necessary information for embedding the media

course_idintegerRequired

Id of the course to embed the media in.

embed_typestringRequired

The type of the embed. Studio uses "embed" to create embedding with media tabs and "bare_embed" to create one with only the media player.

downloadablebooleanOptional

A flag that controlls if the embedded media should be downloadable or not.

Responses
200

The URL to LTI-launch the embedded media. Please note that the URL in the result will work only if it is called with the proper LTI params.

application/json
post
POST /api/public/v1/media/{media_id}/create_embed HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "course_id": 1,
  "embed_type": "text",
  "downloadable": true
}
{
  "embed_url": "text"
}

Download best or specified version of a media

get
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Query parameters
qualitystring · enumOptional

The quality the user wants to download

Possible values:
Responses
302

Redirects to the Notorious URL from where the media can be downloaded. The URL is only valid for 24 hours.

get
GET /api/public/v1/media/{media_id}/download HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Accept: */*

No content

Get users and groups the media is shared with directly

get
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Responses
200

List of users and groups extended with permission type.

application/json
get
GET /api/public/v1/media/{media_id}/permissions HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "users": [
    {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text",
      "permission": "text"
    }
  ],
  "groups": [
    {
      "id": 1,
      "name": "text",
      "permission": "text"
    }
  ]
}

Add permissions to a media

post
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Bodyobject[]

An array with objects describing the permissions to add.

actionstring · enumRequired

The action to perform.

Possible values:
idintegerRequired

The id of the user or group.

share_typestring · enumRequired

The share type.

Possible values:
permission_typestring · enumOptional

The permission type. The default is "view".

Default: viewPossible values:
Responses
200

Permissions were added, the updated list of permissions is returned.

application/json
post
POST /api/public/v1/media/{media_id}/permissions HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 73

[
  {
    "action": "create",
    "id": 1,
    "share_type": "user",
    "permission_type": "view"
  }
]
{
  "users": [
    {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text",
      "permission": "text"
    }
  ],
  "groups": [
    {
      "id": 1,
      "name": "text",
      "permission": "text"
    }
  ]
}

Get perspectives belonging to a media

get
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Responses
200

List of perspectives extended with collection.

application/json
get
GET /api/public/v1/media/{media_id}/perspectives HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "users": [
    {
      "uuid": "text",
      "title": "text",
      "description": "text",
      "duration": 1,
      "created_at": "2025-08-25T07:31:11.261Z",
      "collection": {
        "id": 1,
        "name": "text",
        "type": "text",
        "permission": "text",
        "owner": {
          "id": 1,
          "full_name": "text",
          "display_name": "text",
          "email": "text"
        },
        "created_at": "2025-08-25T07:31:11.261Z",
        "course_id": 1
      }
    }
  ]
}

Get a media's sources by its id

get
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Responses
200

The media sources that were requested.

application/json
get
GET /api/public/v1/media/{media_id}/sources HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "sources": [
    {
      "mime_type": "text",
      "url": "text",
      "target": "text",
      "definition": "text",
      "transcoding_guid": "text",
      "status": "text"
    }
  ]
}

Get a list of users, who have access to the media

get
Authorizations
Path parameters
media_idinteger · int64Required

The ID of the media.

Query parameters
min_permissionstring · enumOptional

Filter users by a minimum permission level. If provided, only users with this permission or higher will be returned. The permissions are hierarchical: 'edit' includes 'view', and 'view' includes 'access'.

Default: accessPossible values:
Responses
200

The users who have access to the media.

application/json
get
GET /api/public/v1/media/{media_id}/users HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "user_permissions": [
    {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text",
      "permission": "text"
    }
  ]
}
PreviousInsightsNextMedia Upload

Last updated

Was this helpful?