Media

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

get

Authorizations

AuthorizationstringRequired

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

401

Authorization information is missing or invalid.

422

Invalid parameters.

get

/media/search

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-12-27T12:05:28.530Z",
      "last_viewed": "2025-12-27",
      "last_viewed_by_student": "2025-12-27",
      "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",
      "archived_at": "2025-12-27T12:05:28.530Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "total_count": 1
  }
}

Get a media by its id

get

Authorizations

AuthorizationstringRequired

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

/media/{media_id}

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-12-27T12:05:28.530Z",
    "last_viewed": "2025-12-27",
    "last_viewed_by_student": "2025-12-27",
    "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",
    "archived_at": "2025-12-27T12:05:28.530Z",
    "collection": {
      "id": 1,
      "name": "text",
      "type": "text",
      "permission": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "created_at": "2025-12-27T12:05:28.530Z",
      "course_id": 1,
      "archived_at": "2025-12-27T12:05:28.530Z"
    }
  }
}

Deletes the specified media object and all related perspectives.

delete

Authorizations

AuthorizationstringRequired

Path parameters

media_idinteger · int64Required

The ID of the media.

Responses

200

The media object that was deleted.

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.

delete

/media/{media_id}

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-12-27T12:05:28.530Z",
    "last_viewed": "2025-12-27",
    "last_viewed_by_student": "2025-12-27",
    "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",
    "archived_at": "2025-12-27T12:05:28.530Z",
    "collection": {
      "id": 1,
      "name": "text",
      "type": "text",
      "permission": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "created_at": "2025-12-27T12:05:28.530Z",
      "course_id": 1,
      "archived_at": "2025-12-27T12:05:28.530Z"
    }
  }
}

Archives the specified media object and all related perspectives.

post

Authorizations

AuthorizationstringRequired

Path parameters

media_idinteger · int64Required

The ID of the media.

Responses

200

The media object that was archived.

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.

post

/media/{media_id}/archive

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

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-12-27T12:05:28.530Z",
    "last_viewed": "2025-12-27",
    "last_viewed_by_student": "2025-12-27",
    "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",
    "archived_at": "2025-12-27T12:05:28.530Z"
  }
}

Get a list of courses which contains the media

get

Authorizations

AuthorizationstringRequired

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

/media/{media_id}/courses

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-12-27T12:05:28.530Z"
    }
  ]
}

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

post

Authorizations

AuthorizationstringRequired

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

/media/{media_id}/create_embed

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

AuthorizationstringRequired

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

/media/{media_id}/download

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

AuthorizationstringRequired

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

/media/{media_id}/permissions

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

AuthorizationstringRequired

Path parameters

media_idinteger · int64Required

The ID of the media.

Body

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

/media/{media_id}/permissions

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: 89

{
  "permissions": [
    {
      "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

AuthorizationstringRequired

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

/media/{media_id}/perspectives

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-12-27T12:05:28.530Z",
      "archived_at": "2025-12-27T12:05:28.530Z",
      "collection": {
        "id": 1,
        "name": "text",
        "type": "text",
        "permission": "text",
        "owner": {
          "id": 1,
          "full_name": "text",
          "display_name": "text",
          "email": "text"
        },
        "created_at": "2025-12-27T12:05:28.530Z",
        "course_id": 1,
        "archived_at": "2025-12-27T12:05:28.530Z"
      }
    }
  ]
}

Get a media's sources by its id

get

Authorizations

AuthorizationstringRequired

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

/media/{media_id}/sources

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

Unarchives the specified media object and all related perspectives.

post

Authorizations

AuthorizationstringRequired

Path parameters

media_idinteger · int64Required

The ID of the media.

Query parameters

collection_idinteger · int64Optional

Move the media to this collection after unarchiving.

Responses

200

The media object that was archived.

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.

post

/media/{media_id}/unarchive

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

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-12-27T12:05:28.530Z",
    "last_viewed": "2025-12-27",
    "last_viewed_by_student": "2025-12-27",
    "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",
    "archived_at": "2025-12-27T12:05:28.530Z"
  }
}

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

get

Authorizations

AuthorizationstringRequired

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

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

/media/{media_id}/users

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

PreviousInsights NextMedia Upload

Last updated 3 months ago

Was this helpful?