Studio API

List caption requests

This endpoint lists caption requests. It works both with auth token and the captioning service auth headers.

GEThttp://tw.instructuremedia.com/api/public/v1/caption_file_requests

Authorization

User_Session

Query parameters

Response

200401403422

List of caption requests

Body

application/json

caption_file_requestsarray of object

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/caption_file_requests?provider=professional&status=requested', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "caption_file_requests": [
    {
      "media_id": "text",
      "job_name": "text",
      "language": "text",
      "media_url": "text",
      "format": "text",
      "callback_url": "text",
      "provider": "text",
      "status": "text",
      "service_type_key": "text"
    }
  ]
}

Send the result of the caption file request.

This endpoint should be used to update a pending caption file request. Each request can be updated once with either fulfilled or failed status.

PATCHhttp://tw.instructuremedia.com/api/public/v1/caption_file_requests/{caption_file_request_id}

Authorization

User_Session

Path parameters

caption_file_request_id*integer

The id of the caption file request to be updated.

Body

multipart/form-data

status*enum

Result of the file request.

processingfulfilledfailed

messagestring

In case the caption creation was not successful you can provide some detail why it could not be completed.

caption_filestring (binary)

The file to be uploaded. The supported file extension is .srt!

Response

202400401403422

The results are successfully saved.

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/caption_file_requests/{caption_file_request_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "status": "processing"
    }),
});
const data = await response.json();

List all available captions for the given media

GEThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/caption_files

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Response

200401403404422

The list of captions that are available for the media.

Body

application/json

caption_filesarray of Api_V1_CaptionFile (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/caption_files', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "caption_files": [
    {
      "url": "text",
      "srclang": "text",
      "subtitle_format": "text",
      "label": "text",
      "status": "text",
      "created_at": "2024-11-21T10:55:02.933Z"
    }
  ]
}

Create a new caption for the given media

POSThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/caption_files

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Query parameters

Body

multipart/form-data

caption_file*string (binary)

The file to be uploaded.

Response

201401403404422

The caption object that was created.

Body

application/json

caption_fileApi_V1_CaptionFile (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/caption_files?srclang=text', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "caption_file": "binary"
    }),
});
const data = await response.json();

Response

201

{
  "caption_file": {
    "url": "text",
    "srclang": "text",
    "subtitle_format": "text",
    "label": "text",
    "status": "text",
    "created_at": "2024-11-21T10:55:02.933Z"
  }
}

Download a caption by id

GEThttp://tw.instructuremedia.com/api/public/v1/caption_files/{caption_file_id}/download

Authorization

User_Session

Path parameters

caption_file_id*integer (int64)

The ID of the caption.

Response

200401403404422

The caption file itself

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/caption_files/{caption_file_id}/download', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

The list of active service types

GEThttp://tw.instructuremedia.com/api/public/v1/captioning_service_types

Authorization

User_Session

Response

200401403404

The list of active service types user has permission to.

Body

application/json

captioning_service_typesarray of Api_V1_CaptioningServiceType (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/captioning_service_types', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "captioning_service_types": [
    {
      "key": "text",
      "label": "text",
      "is_asr": false,
      "description": "text",
      "languages": [
        "text"
      ]
    }
  ]
}

Upsert a service type

The endpoint will insert or update a service type for a captioning service. This endpoint only supports IETF language code

PUThttp://tw.instructuremedia.com/api/public/v1/captioning_service_types/{key}

Authorization

User_Session

Path parameters

key*string

machine readable “id” that will be included with caption file requests when a CaptionService lists available requests.

Body

application/json

An object describing the service type

label*string

description*string

is_asr*boolean

languagesarray of string

IETF language code

Response

200401403404

The service type has been updated successfully

Body

application/json

captioning_service_typesarray of Api_V1_CaptioningServiceType (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/captioning_service_types/{key}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "label": "text",
      "description": "text",
      "is_asr": false
    }),
});
const data = await response.json();

Response

200

{
  "captioning_service_types": [
    {
      "key": "text",
      "label": "text",
      "is_asr": false,
      "description": "text",
      "languages": [
        "text"
      ]
    }
  ]
}

Delete a service type

This endpoint will delete a service type for a captioning service and will remove the associated captioning roles from it.

DELETEhttp://tw.instructuremedia.com/api/public/v1/captioning_service_types/{key}

Authorization

User_Session

Path parameters

key*string

machine readable “id” that will be included with caption file requests when a CaptionService lists available requests.

Response

204401403404

The service type has been deleted successfully

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/captioning_service_types/{key}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

List all collections the authenticated user has permission to.

GEThttp://tw.instructuremedia.com/api/public/v1/collections

Authorization

User_Session

Query parameters

Response

200401

The collections the authenticated user has permission to.

Body

application/json

collectionsarray of Api_V1_Collection (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/collections', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "collections": [
    {
      "name": "text",
      "type": "text",
      "permission": "text",
      "owner": {
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "created_at": "2024-11-21T10:55:02.933Z"
    }
  ]
}

Create a new collection with the specified name

POSThttp://tw.instructuremedia.com/api/public/v1/collections

Authorization

User_Session

Query parameters

Response

201401403404422

The collection object that was created.

Body

application/json

collectionApi_V1_Collection (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/collections?name=text', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

201

{
  "collection": {
    "name": "text",
    "type": "text",
    "permission": "text",
    "owner": {
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "created_at": "2024-11-21T10:55:02.933Z"
  }
}

Get data of a collection

GEThttp://tw.instructuremedia.com/api/public/v1/collections/{collection_id}

Authorization

User_Session

Path parameters

collection_id*integer (int64)

The ID of the collection.

Response

200401403404422

The collection object.

Body

application/json

collectionApi_V1_Collection (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "collection": {
    "name": "text",
    "type": "text",
    "permission": "text",
    "owner": {
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "created_at": "2024-11-21T10:55:02.933Z"
  }
}

Get users and groups who have access to the collection

GEThttp://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/permissions

Authorization

User_Session

Path parameters

collection_id*integer (int64)

The ID of the collection.

Response

200401403404422

List of users and groups extended with permission type.

Body

application/json

usersarray of Api_V1_UserWithPermission (all of)

groupsarray of Api_V1_GroupWithPermission (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/permissions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Add permissions to the collection

POSThttp://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/permissions

Authorization

User_Session

Path parameters

collection_id*integer (int64)

The ID of the collection.

Body

application/json

An array with objects describing the permissions to add or update or destroy.

action*enum

The action to perform.

createupdatedestroy

id*integer

The id of the user or group.

share_type*enum

The share type.

usergroup

permission_typeenum

The permission type. The default is "view".

viewedit

Response

200400401403404422

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

Body

application/json

usersarray of Api_V1_UserWithPermission (all of)

groupsarray of Api_V1_GroupWithPermission (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/permissions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "action": "create",
        "share_type": "user"
      }
    ]),
});
const data = await response.json();

Response

200

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

Get course information

This endpoint will return the course collection information.

GEThttp://tw.instructuremedia.com/api/public/v1/courses/{course_id}

Authorization

User_Session

Path parameters

course_id*integer

ID of the course to get the details of.

Response

200401403404422

After a successful request, the endpoint returns HTTP 200.

Body

application/json

courseApi_V1_Collection (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/courses/{course_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "course": {
    "name": "text",
    "type": "text",
    "permission": "text",
    "owner": {
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "created_at": "2024-11-21T10:55:02.933Z"
  }
}

Get a list of perspectives of a course

This endpoint will return all the perspectives in a course.

GEThttp://tw.instructuremedia.com/api/public/v1/courses/{course_id}/perspectives

Authorization

User_Session

Path parameters

course_id*integer

ID of the course to retrieve perspectives from

Response

200401403404422

After a successful request, the endpoint returns HTTP 200.

Body

application/json

perspectivesarray of Api_V1_PerspectiveWithMedia (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/courses/{course_id}/perspectives', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "perspectives": [
    {
      "uuid": "text",
      "title": "text",
      "description": "text",
      "duration": 0,
      "created_at": "2024-11-21T10:55:02.933Z",
      "media": {
        "title": "text",
        "description": "text",
        "duration": 0,
        "created_at": "2024-11-21T10:55:02.933Z",
        "thumbnail_url": "text",
        "transcoding_status": "text",
        "owner": {
          "full_name": "text",
          "display_name": "text",
          "email": "text"
        },
        "source": "text"
      }
    }
  ]
}

Get details of users for a group

This endpoint will return the users with details and permission for a group

GEThttp://tw.instructuremedia.com/api/public/v1/groups/{group_id}/users

Authorization

User_Session

Path parameters

group_id*integer

ID of the group to retrieve users and their details

Response

200401403404422

After a successful request, the endpoint returns HTTP 200.

Body

application/json

group_usersarray of Api_V1_UserWithPermission (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/groups/{group_id}/users', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "group_users": [
    {
      "full_name": "text",
      "display_name": "text",
      "email": "text",
      "permission": "text"
    }
  ]
}

Update users and theirs permissions for a group

This endpoint will update the users and their permissions for a group

POSThttp://tw.instructuremedia.com/api/public/v1/groups/{group_id}/users/batch_update

Authorization

User_Session

Path parameters

group_id*integer

ID of the group to update users and their permissions

Body

application/json

List of operations to perform

action*enum

Type of action to perform

addupdateremove

user_id*integer

ID of the user to perform the action on

permissionenum

Permission to set for the user when action is add or update

managermember

Response

200401403404422

After a successful request, the endpoint returns HTTP 200.

Body

application/json

group_usersarray of Api_V1_UserWithPermission (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/groups/{group_id}/users/batch_update', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "action": "add"
      }
    ]),
});
const data = await response.json();

Response

200

{
  "group_users": [
    {
      "full_name": "text",
      "display_name": "text",
      "email": "text",
      "permission": "text"
    }
  ]
}

Get media insights overview for a perspective

This endpoint returns a csv file containing video views, time viewed, unique viewers and time based viewership data.

GEThttp://tw.instructuremedia.com/api/public/v1/perspectives/{perspective_uuid}/insights/overview

Authorization

User_Session

Path parameters

perspective_uuid*string

The ID of the perspective.

Query parameters

Response

200401403404422

Returns overview of perspective insights in a CSV.

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/perspectives/{perspective_uuid}/insights/overview', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get all viewers' Insights data for a perspective

This endpoint returns a csv file containing user name, email, role(s), completion rate and time based completion data.

GEThttp://tw.instructuremedia.com/api/public/v1/perspectives/{perspective_uuid}/insights/users

Authorization

User_Session

Path parameters

perspective_uuid*string

The ID of the perspective.

Query parameters

Response

200401403404422

Returns perspective insights for users in a CSV.

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/perspectives/{perspective_uuid}/insights/users', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

List media in a specific collection

GEThttp://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/media

Authorization

User_Session

Path parameters

collection_id*integer (int64)

The ID of the collection

Query parameters

Response

200401403404

The list of media in a specific collection.

Body

application/json

mediaarray of Api_V1_Media (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/media', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "media": [
    {
      "title": "text",
      "description": "text",
      "duration": 0,
      "created_at": "2024-11-21T10:55:02.933Z",
      "thumbnail_url": "text",
      "transcoding_status": "text",
      "owner": {
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "source": "text"
    }
  ]
}

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

POSThttp://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/media

Authorization

User_Session

Path parameters

collection_id*integer (int64)

The ID of the collection

Query parameters

Response

201401403404422501

The media has been uploaded.

Body

application/json

mediaApi_V1_Media (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/media?title=text&url=text', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

201

{
  "media": {
    "title": "text",
    "description": "text",
    "duration": 0,
    "created_at": "2024-11-21T10:55:02.933Z",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "source": "text"
  }
}

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

POSThttp://tw.instructuremedia.com/api/public/v1/media

Authorization

User_Session

Body

application/json

An object containing the necessary information for external media creation

title*string

The title of the media.

url*string

The originating URL where the media can be retrieved.

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

user_idinteger

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

descriptionstring

The description of the media.

collection_idinteger

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_captionboolean

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

Response

201401403422501

The media object that was created.

Body

application/json

mediaApi_V1_Media (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "title": "text",
      "url": "text"
    }),
});
const data = await response.json();

Response

201

{
  "media": {
    "title": "text",
    "description": "text",
    "duration": 0,
    "created_at": "2024-11-21T10:55:02.933Z",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "source": "text"
  }
}

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

GEThttp://tw.instructuremedia.com/api/public/v1/media/search

Authorization

User_Session

Query parameters

Response

200401422

The list of media objects that matched the given query.

Body

application/json

mediaarray of Api_V1_Media (object)

metaobject

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/search', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "media": [
    {
      "title": "text",
      "description": "text",
      "duration": 0,
      "created_at": "2024-11-21T10:55:02.933Z",
      "thumbnail_url": "text",
      "transcoding_status": "text",
      "owner": {
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "source": "text"
    }
  ],
  "meta": {}
}

Generate a URL to which a new media can be uploaded

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

POSThttp://tw.instructuremedia.com/api/public/v1/media/uploads

Authorization

User_Session

Body

application/json

An object containing the necessary information media creation

user_idinteger

ID of the user to upload the media on behalf of

Response

201401403404422

The media upload URL has been generated.

Body

application/json

uploadApi_V1_MediaUpload (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/uploads', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

201

{
  "upload": {
    "url": "text"
  }
}

Complete a media upload

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

POSThttp://tw.instructuremedia.com/api/public/v1/media/uploads/{media_id}/complete

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Body

application/json

An object containing the necessary information for media creation

title*string

The title of the media.

descriptionstring

The description of the media.

auto_captionboolean

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

Response

200400401403404409501

The media object that was created.

Body

application/json

mediaApi_V1_Media (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/uploads/{media_id}/complete', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "title": "text"
    }),
});
const data = await response.json();

Response

200

{
  "media": {
    "title": "text",
    "description": "text",
    "duration": 0,
    "created_at": "2024-11-21T10:55:02.933Z",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "source": "text"
  }
}

Get a media by its id

GEThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Response

200401403404

The media object that was requested.

Body

application/json

mediaApi_V1_MediaWithCollection (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "media": {
    "title": "text",
    "description": "text",
    "duration": 0,
    "created_at": "2024-11-21T10:55:02.933Z",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "source": "text",
    "collection": {
      "name": "text",
      "type": "text",
      "permission": "text",
      "owner": {
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "created_at": "2024-11-21T10:55:02.933Z"
    }
  }
}

Get a list of courses which contains the media

GEThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/courses

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Response

200401403404422

The list of courses that were requested.

Body

application/json

coursesarray of object

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/courses', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "courses": [
    {
      "name": "text",
      "embedded_at": "2024-11-21T10:55:02.933Z"
    }
  ]
}

Download best or specified version of a media

GEThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/download

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Query parameters

Response

302401403404422

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

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/download', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get users and groups the media is shared with directly

GEThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/permissions

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Response

200401403404422

List of users and groups extended with permission type.

Body

application/json

usersarray of Api_V1_UserWithPermission (all of)

groupsarray of Api_V1_GroupWithPermission (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/permissions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Add permissions to a media

POSThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/permissions

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Body

application/json

An array with objects describing the permissions to add.

action*enum

The action to perform.

createupdatedestroy

id*integer

The id of the user or group.

share_type*enum

The share type.

usergroup

permission_typeenum

The permission type. The default is "view".

viewedit

Response

200400401403404422

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

Body

application/json

usersarray of Api_V1_UserWithPermission (all of)

groupsarray of Api_V1_GroupWithPermission (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/permissions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "action": "create",
        "share_type": "user"
      }
    ]),
});
const data = await response.json();

Response

200

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

Get perspectives belonging to a media

GEThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/perspectives

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Response

200401403404422

List of perspectives extended with collection.

Body

application/json

usersarray of Api_V1_PerspectiveWithCollection (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/perspectives', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "users": [
    {
      "uuid": "text",
      "title": "text",
      "description": "text",
      "duration": 0,
      "created_at": "2024-11-21T10:55:02.933Z",
      "collection": {
        "name": "text",
        "type": "text",
        "permission": "text",
        "owner": {
          "full_name": "text",
          "display_name": "text",
          "email": "text"
        },
        "created_at": "2024-11-21T10:55:02.933Z"
      }
    }
  ]
}

Get a media's sources by its id

GEThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/sources

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Response

200401403404

The media sources that were requested.

Body

application/json

sourcesarray of Api_V1_MediaSource (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/sources', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

GEThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/users

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Response

200401403404422

The users who have access to the media.

Body

application/json

user_permissionsarray of Api_V1_UserWithPermission (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/users', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "user_permissions": [
    {
      "full_name": "text",
      "display_name": "text",
      "email": "text",
      "permission": "text"
    }
  ]
}

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

POSThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/create_embed

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Body

application/json

An object containing the necessary information for embedding the media

course_id*integer

Id of the course to embed the media in.

embed_type*string

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.

downloadableboolean

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

Response

200401403404422

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.

Body

application/json

embed_urlstring

The URL to LTI-launch the embedded media.

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/create_embed', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "embed_type": "text"
    }),
});
const data = await response.json();

Response

200

{
  "embed_url": "text"
}

Test endpoint for the Studio public API

Allows for verification of a consumer's plumbing to the public API.

GEThttp://tw.instructuremedia.com/api/public/v1/ping

Authorization

User_Session

Response

200401

If called with correct authentication, this API should have a text reply of 'pong'.

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/ping', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Show all tags for the given media

GEThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/tags

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Response

201401403404

The tag object(s) for the given media.

Body

application/json

tagsarray of Api_V1_Tag (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/tags', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

201

{
  "tags": [
    {
      "name": "text"
    }
  ]
}

Create a new tag for the given media

POSThttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/tags

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

Query parameters

Response

201401403404

The tag object that was created.

Body

application/json

tagApi_V1_Tag (object)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/tags?name=text', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

201

{
  "tag": {
    "name": "text"
  }
}

Delete a tag by its id

DELETEhttp://tw.instructuremedia.com/api/public/v1/media/{media_id}/tags/{tag_id}

Authorization

User_Session

Path parameters

media_id*integer (int64)

The ID of the media.

tag_id*integer (int64)

The ID of the tag.

Response

200401403404

The media tag has been deleted.

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/media/{media_id}/tags/{tag_id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Transfer all media owned by one user to another

The endpoint transfers all not shared media objects owned by the user to a new owner. We transfer the media objects themselves, all perspectives stored in the "My Library" and in custom collections.

POSThttp://tw.instructuremedia.com/api/public/v1/transfer_media

Authorization

User_Session

Body

application/json

An object describing from which user and to what user should be the media transferred.

from_user_id*integer

to_user_id*integer

Response

200400401403422

The media has been successfully transferred to the target user.

Body

application/json

not_transferred_perspective_idsarray of string

not_transferred_collection_idsarray of integer

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/transfer_media', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "not_transferred_perspective_ids": [
    "text"
  ],
  "not_transferred_collection_ids": []
}

Get data of a user

GEThttp://tw.instructuremedia.com/api/public/v1/users/{user_id}

Authorization

User_Session

Path parameters

user_id*integer (int64)

The ID of the user.

Response

200401403404422

The user object.

Body

application/json

userApi_V1_UserWithRoles (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/users/{user_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "user": {
    "full_name": "text",
    "display_name": "text",
    "email": "text",
    "role_names": [
      "text"
    ]
  }
}

Get a list of media the user has access to.

GEThttp://tw.instructuremedia.com/api/public/v1/users/{user_id}/media

Authorization

User_Session

Path parameters

user_id*integer (int64)

The ID of the user.

Query parameters

Response

200401403404422

The requested media list extended with permission of the user on the media.

Body

application/json

mediaarray of Api_V1_MediaWithPermission (all of)

metaobject

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/users/{user_id}/media', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "media": [
    {
      "title": "text",
      "description": "text",
      "duration": 0,
      "created_at": "2024-11-21T10:55:02.933Z",
      "thumbnail_url": "text",
      "transcoding_status": "text",
      "owner": {
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "source": "text",
      "permission": "text"
    }
  ],
  "meta": {}
}

Search users.

GEThttp://tw.instructuremedia.com/api/public/v1/users/search

Authorization

User_Session

Query parameters

Response

200400401403422

The list of user objects.

Body

application/json

usersarray of Api_V1_UserWithRoles (all of)

metaobject

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/users/search', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "users": [
    {
      "full_name": "text",
      "display_name": "text",
      "email": "text",
      "role_names": [
        "text"
      ]
    }
  ],
  "meta": {}
}

Add/Remove roles from users

PUThttp://tw.instructuremedia.com/api/public/v1/users/roles

Authorization

User_Session

Body

application/json

An object containing list of actions to be applied on users roles

actionsarray of object

Response

200400401403404422

Role updates are successfully applied, the updated list of user objects

Body

application/json

usersarray of Api_V1_UserWithRoles (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://tw.instructuremedia.com/api/public/v1/users/roles', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "users": [
    {
      "full_name": "text",
      "display_name": "text",
      "email": "text",
      "role_names": [
        "text"
      ]
    }
  ]
}