Instructure Developer Documentation Portal

Media

PreviousInsights NextMedia Upload

Last updated 1 day ago

Was this helpful?

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 date of the search interval. Format YYYY-MM-DD

end_datestring · dateOptional

End date of the search interval. 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

401

Authorization information is missing or invalid.

422

Invalid parameters.

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-05-16T04:02:40.451Z",
      "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

401

Authorization information is missing or invalid.

403

If a user without proper permissions tries to call this endpoint, the call is rejected with 403 Forbidden.

404

The media ID was not found.

get

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

{
  "media": {
    "id": 1,
    "full_name": "text",
    "display_name": "text",
    "email": "text",
    "collection": {
      "id": 1,
      "name": "text",
      "type": "text",
      "permission": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "created_at": "2025-05-16T04:02:40.451Z",
      "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

401

Authorization information is missing or invalid.

403

If a user without proper permissions tries to call this endpoint, the call is rejected with 403 Forbidden.

404

The media was not found by ID.

422

Invalid media_id is provided.

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-05-16T04:02:40.451Z"
    }
  ]
}

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.

401

Authorization information is missing or invalid.

403

If a user without permission tries to call this endpoint, the call is rejected with 403 Forbidden.

404

The media or its version was not found.

422

Invalid media_id is provided or the media is external.

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

401

Authorization information is missing or invalid.

403

If a user without proper permissions tries to call this endpoint, the call is rejected with 403 Forbidden.

404

The media was not found by ID.

422

Invalid media_id is provided.

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"
    }
  ]
}

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

401

Authorization information is missing or invalid.

403

If a user without proper permissions tries to call this endpoint, the call is rejected with 403 Forbidden.

404

The media was not found by ID.

422

Invalid media_id is provided.

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-05-16T04:02:40.451Z",
      "collection": {
        "id": 1,
        "name": "text",
        "type": "text",
        "permission": "text",
        "owner": {
          "id": 1,
          "full_name": "text",
          "display_name": "text",
          "email": "text"
        },
        "created_at": "2025-05-16T04:02:40.451Z",
        "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

401

Authorization information is missing or invalid.

403

If a user without proper permissions tries to call this endpoint, the call is rejected with 403 Forbidden.

404

The media was not found by ID.

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.

Responses

200

The users who have access to the media.

application/json

401

Authorization information is missing or invalid.

403

If a user without permission tries to call this endpoint, the call is rejected with 403 Forbidden.

404

The media was not found by ID.

422

Invalid media_id is provided.

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"
    }
  ]
}

Add permissions to a media

post

Authorizations

Path parameters

media_idinteger · int64Required

The ID of the media.

Body

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

400

One ore more permission was not found or can not be created, because already exists

401

Authorization information is missing or invalid.

403

If a user without proper permissions tries to call this endpoint, the call is rejected with 403 Forbidden.

404

The media was not found by ID.

422

Invalid media_id is provided.

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"
    }
  ]
}

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

401

Authorization information is missing or invalid.

403

If a user without proper permissions tries to call this endpoint, the call is rejected with 403 Forbidden.

404

The media was not found by ID.

422

Invalid media_id is provided.

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"
}