Instructure Developer Documentation Portal

Studio API

PreviousInstructure Media NextQuizzes

Last updated 11 months ago

Was this helpful?

List caption requests

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

get

/caption_file_requests

Authorizations

Query parameters

providerstring · enumrequired

Provider of the caption. The only option is "professional"

Options: professional

statusstring · enumrequired

Status of the caption request. The only possible value now is "requested"

Options: requested

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/caption_file_requests?provider=professional&status=requested' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

422

{
  "caption_file_requests": []
}

List of caption requests

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.

patch

/caption_file_requests/{caption_file_request_id}

Authorizations

Path parameters

caption_file_request_idintegerrequired

The id of the caption file request to be updated.

Body

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!

statusstring · enumrequired

Result of the file request.

Options: processing, fulfilled, failed

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'http://tw.instructuremedia.com/api/public/v1/caption_file_requests/{caption_file_request_id}' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --data '{"status":"processing"}'

202

400

401

403

422

No body

The results are successfully saved.

List all available captions for the given media

get

/media/{media_id}/caption_files

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/caption_files' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

{
  "caption_files": [
    {
      "id": 1,
      "url": "text",
      "srclang": "text",
      "subtitle_format": "text",
      "label": "text",
      "status": "text",
      "created_at": "2025-02-20T19:04:49.039Z"
    }
  ]
}

The list of captions that are available for the media.

Create a new caption for the given media

post

/media/{media_id}/caption_files

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Query parameters

srclangstringrequired

The language of the caption.

Body

caption_filestring · binaryrequired

The file to be uploaded.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/caption_files?srclang=text' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --data '{"caption_file":"text"}'

201

401

403

404

422

{
  "caption_file": {
    "id": 1,
    "url": "text",
    "srclang": "text",
    "subtitle_format": "text",
    "label": "text",
    "status": "text",
    "created_at": "2025-02-20T19:04:49.039Z"
  }
}

The caption object that was created.

Download a caption by id

get

/caption_files/{caption_file_id}/download

Authorizations

Path parameters

caption_file_idinteger · int64required

The ID of the caption.

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/caption_files/{caption_file_id}/download' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

No body

The caption file itself

The list of active service types

get

/captioning_service_types

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/captioning_service_types' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

{
  "captioning_service_types": [
    {
      "id": 1,
      "key": "text",
      "label": "text",
      "is_asr": true,
      "description": "text",
      "languages": [
        "text"
      ]
    }
  ]
}

The list of active service types user has permission to.

Upsert a service type

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

put

/captioning_service_types/{key}

Authorizations

Path parameters

keystringrequired

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

Body

labelstringrequired

descriptionstringrequired

is_asrbooleanrequired

languagesstring[]

IETF language code

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'http://tw.instructuremedia.com/api/public/v1/captioning_service_types/{key}' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"label":"text","description":"text","is_asr":true,"languages":[null]}'

200

401

403

404

{
  "captioning_service_types": [
    {
      "id": 1,
      "key": "text",
      "label": "text",
      "is_asr": true,
      "description": "text",
      "languages": [
        "text"
      ]
    }
  ]
}

The service type has been updated successfully

Delete a service type

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

delete

/captioning_service_types/{key}

Authorizations

Path parameters

keystringrequired

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

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'http://tw.instructuremedia.com/api/public/v1/captioning_service_types/{key}' \
  --header 'Authorization: YOUR_API_KEY'

204

401

403

404

No body

The service type has been deleted successfully

List all collections the authenticated user has permission to.

get

/collections

Authorizations

Query parameters

pageinteger · default: 1

The page to retrieve. Default: 1.

per_pageinteger · max: 50 · default: 20

The number of results per page. Default: 20, Max: 50.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/collections' \
  --header 'Authorization: YOUR_API_KEY'

200

401

{
  "collections": [
    {
      "id": 1,
      "name": "text",
      "type": "text",
      "permission": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "created_at": "2025-02-20T19:04:49.039Z",
      "course_id": 1
    }
  ]
}

The collections the authenticated user has permission to.

Create a new collection with the specified name

post

/collections

Authorizations

Query parameters

namestringrequired

The name of the collection.

user_idinteger

ID of the user to create the collection on behalf of. If not provided, the collection will be created in the requestor's library

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/collections?name=text' \
  --header 'Authorization: YOUR_API_KEY'

201

401

403

404

422

{
  "collection": {
    "id": 1,
    "name": "text",
    "type": "text",
    "permission": "text",
    "owner": {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "created_at": "2025-02-20T19:04:49.039Z",
    "course_id": 1
  }
}

The collection object that was created.

Get data of a collection

get

/collections/{collection_id}

Authorizations

Path parameters

collection_idinteger · int64required

The ID of the collection.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

{
  "collection": {
    "id": 1,
    "name": "text",
    "type": "text",
    "permission": "text",
    "owner": {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "created_at": "2025-02-20T19:04:49.039Z",
    "course_id": 1
  }
}

The collection object.

Get users and groups who have access to the collection

get

/collections/{collection_id}/permissions

Authorizations

Path parameters

collection_idinteger · int64required

The ID of the collection.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/permissions' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

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

List of users and groups extended with permission type.

Add permissions to the collection

post

/collections/{collection_id}/permissions

Authorizations

Path parameters

collection_idinteger · int64required

The ID of the collection.

Body

idintegerrequired

The id of the user or group.

actionstring · enumrequired

The action to perform.

Options: create, update, destroy

share_typestring · enumrequired

The share type.

Options: user, group

permission_typestring · enum · default: view

The permission type. The default is "view".

Options: view, edit

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/permissions' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '[{"id":1,"action":"create","share_type":"user","permission_type":"view"}]'

200

400

401

403

404

422

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

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

Get course information

This endpoint will return the course collection information.

get

/courses/{course_id}

Authorizations

Path parameters

course_idintegerrequired

ID of the course to get the details of.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/courses/{course_id}' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

{
  "course": {
    "id": 1,
    "name": "text",
    "type": "text",
    "permission": "text",
    "owner": {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "created_at": "2025-02-20T19:04:49.039Z",
    "course_id": 1
  }
}

After a successful request, the endpoint returns HTTP 200.

Get a list of perspectives of a course

This endpoint will return all the perspectives in a course.

get

/courses/{course_id}/perspectives

Authorizations

Path parameters

course_idintegerrequired

ID of the course to retrieve perspectives from

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/courses/{course_id}/perspectives' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

{
  "perspectives": [
    {
      "uuid": "text",
      "title": "text",
      "description": "text",
      "duration": 1,
      "created_at": "2025-02-20T19:04:49.039Z",
      "media": {
        "id": 1,
        "title": "text",
        "description": "text",
        "duration": 1,
        "created_at": "2025-02-20T19:04:49.039Z",
        "thumbnail_url": "text",
        "transcoding_status": "text",
        "owner": {
          "id": 1,
          "full_name": "text",
          "display_name": "text",
          "email": "text"
        },
        "size": 1,
        "source": "text"
      }
    }
  ]
}

After a successful request, the endpoint returns HTTP 200.

Get details of users for a group

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

get

/groups/{group_id}/users

Authorizations

Path parameters

group_idintegerrequired

ID of the group to retrieve users and their details

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/groups/{group_id}/users' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

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

After a successful request, the endpoint returns HTTP 200.

Update users and theirs permissions for a group

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

post

/groups/{group_id}/users/batch_update

Authorizations

Path parameters

group_idintegerrequired

ID of the group to update users and their permissions

Body

user_idintegerrequired

ID of the user to perform the action on

actionstring · enumrequired

Type of action to perform

Options: add, update, remove

permissionstring · enum

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

Options: manager, member

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/groups/{group_id}/users/batch_update' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '[{"user_id":1,"action":"add","permission":"manager"}]'

200

401

403

404

422

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

After a successful request, the endpoint returns HTTP 200.

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.

get

/perspectives/{perspective_uuid}/insights/overview

Authorizations

Path parameters

perspective_uuidstringrequired

The ID of the perspective.

Query parameters

rolestring · enum

A role to filter the users by. If not provided all insights data is aggregated.

Options: Teacher, Student

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/perspectives/{perspective_uuid}/insights/overview' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

No body

Returns overview of perspective insights in a CSV.

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.

get

/perspectives/{perspective_uuid}/insights/users

Authorizations

Path parameters

perspective_uuidstringrequired

The ID of the perspective.

Query parameters

rolestring · enum

A role to filter the users by. If not provided all insights data is aggregated.

Options: Teacher, Student

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/perspectives/{perspective_uuid}/insights/users' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

No body

Returns perspective insights for users in a CSV.

List media in a specific collection

get

/collections/{collection_id}/media

Authorizations

Path parameters

collection_idinteger · int64required

The ID of the collection

Query parameters

pageinteger · default: 1

The page to retrieve. Default: 1.

per_pageinteger · max: 50 · default: 20

The number of results per page. Default: 20, Max: 50.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/media' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

{
  "media": [
    {
      "id": 1,
      "title": "text",
      "description": "text",
      "duration": 1,
      "created_at": "2025-02-20T19:04:49.039Z",
      "thumbnail_url": "text",
      "transcoding_status": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "size": 1,
      "source": "text"
    }
  ]
}

The list of media in a specific collection.

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

post

/collections/{collection_id}/media

Authorizations

Path parameters

collection_idinteger · int64required

The ID of the collection

Query parameters

titlestringrequired

The title of the media.

urlstringrequired

The originating URL where the media can be retrieved.

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

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.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/collections/{collection_id}/media?title=text&url=text' \
  --header 'Authorization: YOUR_API_KEY'

201

401

403

404

422

501

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-02-20T19:04:49.039Z",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "size": 1,
    "source": "text"
  }
}

The media has been uploaded.

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

post

/media

Authorizations

Body

titlestringrequired

The title of the media.

urlstringrequired

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.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/media' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"title":"text","url":"text"}'

201

401

403

422

501

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-02-20T19:04:49.039Z",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "size": 1,
    "source": "text"
  }
}

The media object that was created.

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

get

/media/search

Authorizations

Query parameters

titlestring

Substring of the media title you want to search for.

min_sizeinteger

Minimum size of the media in bytes.

max_sizeinteger

Maximum size of the media in bytes.

start_datestring · date

Start date of the search interval. Format YYYY-MM-DD

end_datestring · date

End date of the search interval. Format YYYY-MM-DD

ownerstring · email

Email address of the owner of the media.

tagstring

The full name of the tag, you want to list media objects for.

sourcestring · enum

The source of the media you want to list media objects for.

Options: upload, youtube, vimeo, zoom

pageinteger · default: 1

The page to retrieve. Default: 1.

per_pageinteger · max: 50 · default: 20

The number of results per page. Default: 20, Max: 50.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/search' \
  --header 'Authorization: YOUR_API_KEY'

200

401

422

{
  "media": [
    {
      "id": 1,
      "title": "text",
      "description": "text",
      "duration": 1,
      "created_at": "2025-02-20T19:04:49.039Z",
      "thumbnail_url": "text",
      "transcoding_status": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "size": 1,
      "source": "text"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "total_count": 1
  }
}

The list of media objects that matched the given query.

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'

post

/media/uploads

Authorizations

Body

user_idinteger

ID of the user to upload the media on behalf of

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/uploads' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json'

201

401

403

404

422

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

The media upload URL has been generated.

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"

post

/media/uploads/{media_id}/complete

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Body

titlestringrequired

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.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/uploads/{media_id}/complete' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"title":"text"}'

200

400

401

403

404

409

501

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-02-20T19:04:49.039Z",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "size": 1,
    "source": "text"
  }
}

The media object that was created.

Get a media by its id

get

/media/{media_id}

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

{
  "media": {
    "id": 1,
    "title": "text",
    "description": "text",
    "duration": 1,
    "created_at": "2025-02-20T19:04:49.039Z",
    "thumbnail_url": "text",
    "transcoding_status": "text",
    "owner": {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text"
    },
    "size": 1,
    "source": "text",
    "collection": {
      "id": 1,
      "name": "text",
      "type": "text",
      "permission": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "created_at": "2025-02-20T19:04:49.039Z",
      "course_id": 1
    }
  }
}

The media object that was requested.

Get a list of courses which contains the media

get

/media/{media_id}/courses

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/courses' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

{
  "courses": [
    {
      "id": 1,
      "name": "text",
      "embedded_at": "2025-02-20T19:04:49.039Z"
    }
  ]
}

The list of courses that were requested.

Download best or specified version of a media

get

/media/{media_id}/download

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Query parameters

qualitystring · enum

The quality the user wants to download

Options: highest, high, standard, low

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/download' \
  --header 'Authorization: YOUR_API_KEY'

302

401

403

404

422

No body

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

Get users and groups the media is shared with directly

get

/media/{media_id}/permissions

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/permissions' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

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

List of users and groups extended with permission type.

Add permissions to a media

post

/media/{media_id}/permissions

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Body

idintegerrequired

The id of the user or group.

actionstring · enumrequired

The action to perform.

Options: create, update, destroy

share_typestring · enumrequired

The share type.

Options: user, group

permission_typestring · enum · default: view

The permission type. The default is "view".

Options: view, edit

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/permissions' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '[{"id":1,"action":"create","share_type":"user","permission_type":"view"}]'

200

400

401

403

404

422

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

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

Get perspectives belonging to a media

get

/media/{media_id}/perspectives

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/perspectives' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

{
  "users": [
    {
      "uuid": "text",
      "title": "text",
      "description": "text",
      "duration": 1,
      "created_at": "2025-02-20T19:04:49.039Z",
      "collection": {
        "id": 1,
        "name": "text",
        "type": "text",
        "permission": "text",
        "owner": {
          "id": 1,
          "full_name": "text",
          "display_name": "text",
          "email": "text"
        },
        "created_at": "2025-02-20T19:04:49.039Z",
        "course_id": 1
      }
    }
  ]
}

List of perspectives extended with collection.

Get a media's sources by its id

get

/media/{media_id}/sources

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/sources' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

{
  "sources": [
    {
      "mime_type": "text",
      "url": "text",
      "target": "text",
      "definition": "text",
      "transcoding_guid": "text",
      "status": "text"
    }
  ]
}

The media sources that were requested.

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

get

/media/{media_id}/users

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/users' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

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

The users who have access to the media.

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

post

/media/{media_id}/create_embed

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Body

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.

downloadableboolean

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/create_embed' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"course_id":1,"embed_type":"text"}'

200

401

403

404

422

{
  "embed_url": "text"
}

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.

Test endpoint for the Studio public API

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

get

/ping

Authorizations

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/ping' \
  --header 'Authorization: YOUR_API_KEY'

200

401

No body

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

Show all tags for the given media

get

/media/{media_id}/tags

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/tags' \
  --header 'Authorization: YOUR_API_KEY'

201

401

403

404

{
  "tags": [
    {
      "id": 1,
      "name": "text"
    }
  ]
}

The tag object(s) for the given media.

Create a new tag for the given media

post

/media/{media_id}/tags

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

Query parameters

namestringrequired

The name of the tag.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/tags?name=text' \
  --header 'Authorization: YOUR_API_KEY'

201

401

403

404

{
  "tag": {
    "id": 1,
    "name": "text"
  }
}

The tag object that was created.

Delete a tag by its id

delete

/media/{media_id}/tags/{tag_id}

Authorizations

Path parameters

media_idinteger · int64required

The ID of the media.

tag_idinteger · int64required

The ID of the tag.

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'http://tw.instructuremedia.com/api/public/v1/media/{media_id}/tags/{tag_id}' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

No body

The media tag has been deleted.

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.

post

/transfer_media

Authorizations

Body

from_user_idintegerrequired

to_user_idintegerrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'http://tw.instructuremedia.com/api/public/v1/transfer_media' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"from_user_id":1,"to_user_id":1}'

200

400

401

403

422

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

The media has been successfully transferred to the target user.

Get data of a user

get

/users/{user_id}

Authorizations

Path parameters

user_idinteger · int64required

The ID of the user.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/users/{user_id}' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

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

The user object.

Get a list of media the user has access to.

get

/users/{user_id}/media

Authorizations

Path parameters

user_idinteger · int64required

The ID of the user.

Query parameters

pageinteger

The number of the page you want to query. Default 1

per_pageinteger

The number of items per page. Default 20, maximum 50

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/users/{user_id}/media' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

422

{
  "media": [
    {
      "id": 1,
      "title": "text",
      "description": "text",
      "duration": 1,
      "created_at": "2025-02-20T19:04:49.039Z",
      "thumbnail_url": "text",
      "transcoding_status": "text",
      "owner": {
        "id": 1,
        "full_name": "text",
        "display_name": "text",
        "email": "text"
      },
      "size": 1,
      "source": "text",
      "permission": "text"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "total_count": 1
  }
}

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

Search users.

get

/users/search

Authorizations

Query parameters

rolestring · enum

A role to filter the users by.

Options: Admin, Teacher, Student, Observer

emailstring

Email address of the user.

pageinteger · default: 1

The page to retrieve. Default: 1.

per_pageinteger · max: 50 · default: 20

The number of results per page. Default: 20, Max: 50.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'http://tw.instructuremedia.com/api/public/v1/users/search' \
  --header 'Authorization: YOUR_API_KEY'

200

400

401

403

422

{
  "users": [
    {
      "id": 1,
      "full_name": "text",
      "display_name": "text",
      "email": "text",
      "role_names": [
        "text"
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "total_count": 1
  }
}

The list of user objects.

Add/Remove roles from users

put

/users/roles

Authorizations

Body

actionsobject[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'http://tw.instructuremedia.com/api/public/v1/users/roles' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"actions":[{"user_id":1,"action":"add","role":"Admin"}]}'

200

400

401

403

404

422

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

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