Community

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
post
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-27T08:23:35.535Z",
    "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
post
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-27T08:23:35.535Z",
    "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
post
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
post
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-27T08:23:35.535Z",
    "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"
  }
}
PreviousMediaNextPing

Last updated

Was this helpful?