Media Upload

Create a new media in the specified collection from an existing file accessible by URL

post

Authorizations

Path parameters

collection_idinteger · int64Required

The ID of the collection

Query parameters

urlstringRequired

The originating URL where the media can be retrieved.

Pattern: ^http[s]?:\/?\/

titlestringOptional

The title of the media. Required for non-external media.

descriptionstringOptional

The description of the media.

auto_captionbooleanOptional

Whether to request auto-captioning for the media (false by default). This option is only available if auto-captioning is enabled for your account.

Default: false

user_idinteger · int64Optional

An admin user can create the media on behalf of a user by specifying the user ID.

is_externalbooleanOptional

Whether the media is external (false by default). Only YouTube and Vimeo URLs are supported.

Default: false

Responses

201

The media has been uploaded.

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 collection was not found by ID.

422

Invalid collection_id is provided.

501

Auto-captioning was requested but is not enabled for the account.

post

HTTPcURLJavaScriptPython

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

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-06-06T18:58:01.860Z",
    "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"
  }
}

Create a new media in "My Uploads" or specified collection from an existing file accessible by URL

post

Authorizations

Body

An object containing the necessary information for external media creation

urlstringRequired

The originating URL where the media can be retrieved.

Pattern: ^http[s]?:\/?\/

titlestringOptional

The title of the media. Required for non-external media.

user_idintegerOptional

ID of the user to upload the media on behalf of. if not provided, the video will be uploaded to requestor's user library

descriptionstringOptional

The description of the media.

collection_idintegerOptional

The ID of a collection, user_id and collection_id can not be sent together as if user_id is provided the media will be uploaded to user's user library

auto_captionbooleanOptional

Whether to request auto-captioning for the media (false by default). This option is only available if auto-captioning is enabled for your account.

is_externalbooleanOptional

Whether the media is external or not (false by default). Only YouTube and Vimeo are supported.

Responses

201

The media object that was created.

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.

422

Invalid parameters.

501

Auto-captioning was requested but is not enabled for the account.

post

HTTPcURLJavaScriptPython

POST /api/public/v1/media HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 119

{
  "url": "text",
  "title": "text",
  "user_id": 1,
  "description": "text",
  "collection_id": 1,
  "auto_caption": true,
  "is_external": true
}

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-06-06T18:58:01.860Z",
    "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"
  }
}

Generate a URL to which a new media can be uploaded

post

This URL can be used in a PUT request to upload a local file, ex: curl -T /path/to/local/media.file 'URL'

Authorizations

Body

An object containing the necessary information media creation

user_idintegerOptional

ID of the user to upload the media on behalf of

Responses

201

The media upload URL has been generated.

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 user was not found by id.

422

Invalid user_id is provided.

post

HTTPcURLJavaScriptPython

POST /api/public/v1/media/uploads HTTP/1.1
Host: tw.instructuremedia.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 13

{
  "user_id": 1
}

{
  "upload": {
    "id": 1,
    "url": "text"
  }
}

Complete a media upload

post

Signifies that a media file has been uploaded to a previously-created upload URL and is ready to appear in "My Uploads"

Authorizations

Path parameters

media_idinteger · int64Required

The ID of the media.

Body

An object containing the necessary information for media creation

titlestringRequired

The title of the media.

descriptionstringOptional

The description of the media.

auto_captionbooleanOptional

Whether to request auto-captioning for the media (false by default). This option is only available if auto-captioning is enabled for your account.

Responses

200

The media object that was created.

application/json

400

The title is missing

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.

409

This upload has already been completed.

501

Auto-captioning was requested but is not enabled for the account.

post

HTTPcURLJavaScriptPython

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

{
  "title": "text",
  "description": "text",
  "auto_caption": true
}

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-06-06T18:58:01.860Z",
    "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"
  }
}