Instructure Developer Documentation Portal
Community
  • Introduction
  • Services
    • Elevate Standards Alignment - AB Connect API
      • Introduction
        • Authentication
        • Addressing Object Properties
        • Requesting Additional Properties in the Response
        • Filtering Using ODATA Like Statements
        • Sorting
        • Facets
        • Paging Data
        • Call Throttling
        • Working with Related Object
        • Error Responses
        • Character Set Support
        • How To Articles, Recommendations and Suggestions
        • Examples
        • Using AB Connect's Embeddable Widgets
      • Reference
        • Standards
        • Standard Collections
        • Events
        • Topics
        • Concepts
        • Assets
        • Asset Definitions
        • Asset Collections
        • Managing and Predicting Relationships
        • Providers
    • Canvas LMS
      • Basics
        • GraphQL
        • API Change Log
        • SIS IDs
        • Pagination
        • Throttling
        • Compound Documents
        • File Uploads
        • API Endpoint Attributes
        • Masquerading
      • OAuth2
        • OAuth2 Overview
        • OAuth2 Endpoints
        • Developer Keys
      • Resources
        • Access Tokens
        • Account Calendars
        • Account Domain Lookups
        • Account Notifications
        • Account Reports
        • Accounts
        • Accounts (LTI)
        • Admins
        • Analytics
        • Announcement External Feeds
        • Announcements
        • API Token Scopes
        • Appointment Groups
        • Assignment Extensions
        • Assignment Groups
        • Assignments
        • Authentication Providers
        • Authentications Log
        • Blackout Dates
        • BlockEditorTemplate
        • Blueprint Courses
        • Bookmarks
        • Brand Configs
        • Calendar Events
        • Collaborations
        • CommMessages
        • Communication Channels
        • Conferences
        • Content Exports
        • Content Migrations
        • Content Security Policy Settings
        • Content Shares
        • Conversations
        • Course Audit log
        • Course Pace
        • Course Quiz Extensions
        • Course Reports
        • Courses
        • Custom Gradebook Columns
        • Developer Key Account Bindings
        • Developer Keys
        • Discussion Topics
        • Enrollment Terms
        • Enrollments
        • ePortfolios
        • ePub Exports
        • Error Reports
        • External Tools
        • Favorites
        • Feature Flags
        • Files
        • Grade Change Log
        • Gradebook History
        • Grading Period Sets
        • Grading Periods
        • Grading Standards
        • Group Categories
        • Groups
        • History
        • InstAccess tokens
        • JWTs
        • Late Policy
        • Learning Object Dates
        • Line Items
        • LiveAssessments
        • Logins
        • LTI Launch Definitions
        • LTI Registrations
        • LTI Resource Links
        • Media Objects
        • Moderated Grading
        • Modules
        • Names and Role
        • New Quiz Items
        • New Quizzes
        • New Quizzes Accommodations
        • New Quizzes Reports
        • Notification Preferences
        • Originality Reports
        • Outcome Groups
        • Outcome Imports
        • Outcome Results
        • Outcomes
        • Pages
        • Peer Reviews
        • Planner
        • Poll Sessions
        • PollChoices
        • Polls
        • PollSubmissions
        • Proficiency Ratings
        • Progress
        • Public JWK
        • Quiz Assignment Overrides
        • Quiz Extensions
        • Quiz IP Filters
        • Quiz Question Groups
        • Quiz Questions
        • Quiz Reports
        • Quiz Statistics
        • Quiz Submission Events
        • Quiz Submission Files
        • Quiz Submission Questions
        • Quiz Submission User List
        • Quiz Submissions
        • Quizzes
        • Result
        • Roles
        • Rubrics
        • Sandboxes
        • Score
        • Search
        • Sections
        • Services
        • Shared Brand Configs
        • SIS Import Errors
        • SIS Imports
        • SIS Integration
        • Smart Search
        • Submission Comments
        • Submissions
        • Tabs
        • Temporary Enrollment Pairings
        • User Observees
        • Users
        • What If Grades
      • Outcomes
        • Outcomes CSV Format
      • Group Categories
        • Group Categories CSV Format
      • SIS
        • SIS CSV Format
      • External Tools
        • LTI
          • Introduction
          • Registration
          • Launch Overview
          • Configuring
          • Variable Substitutions
          • Deep Linking
          • Grading
          • Provisioning
          • PostMessage
          • Platform Notification Service
          • Placements
            • Placements Overview
            • Navigation
            • Homework Submission
            • Editor Button
            • Migration Selection
            • Link Selection (Modules)
            • Assignment Selection
            • Collaborations
        • xAPI
        • Canvas Roles
        • Plagiarism Detection Platform
          • Overview
          • Plagiarism Detection Platform Assignments
          • Plagiarism Detection Platform Users
          • Plagiarism Detection Submissions
          • Webhooks Subscriptions for Plagiarism Platform
          • JWT Access Tokens
      • Data Services
        • Live Events
          • Overview
            • Introduction
            • Setup
            • Caliper
            • Metadata
          • Event Format
            • Canvas
              • Account
              • Asset
              • Assignment
              • Attachment
              • Content
              • Conversation
              • Course
              • Discussion
              • Enrollment
              • Grade
              • Group
              • Learning
              • Logged
              • Module
              • Outcome
              • Outcomes
              • Plagiarism
              • Quiz
              • Rubric
              • Sis
              • Submission
              • Syllabus
              • User
              • Wiki
            • Caliper IMS 1.1
              • Assessment
              • Basic
              • Forum
              • Grading
              • Navigation Events
              • Session
    • Catalog
      • APIs
        • Analytics
        • Bulk Enrollments
        • Catalogs
        • Certificates
        • Completed Certificates
        • Courses
        • Email Domain Set
        • Enrollments
        • Orders
        • Programs
        • Progresses
        • Tags
        • User Registrations
        • Users
        • Waitlist Applicants
    • Credentials
      • Getting Started
      • Authentication
        • Password-Based Authentication
        • Authorization Code-Based Authentication
      • Pagination
      • APIs
        • Assertions
        • Backpack
        • Badgeclasses
        • Issuers
        • Organizations
        • Users
      • Release Notes
    • Data Access Platform
      • Key Concepts
      • Data Formats
      • Rate Limits & Policies
      • Datasets
        • Namespaces
          • canvas
            • canvas types
          • canvas_logs
          • catalog
        • Additional Notes
        • Entity Relationship Diagram
      • Query API
        • Authentication
        • Reference
      • Command Line (DAP CLI)
        • Getting Started
        • Secure Connection
        • Reference
          • dap snapshot
          • dap incremental
          • dap list
          • dap schema
          • dap initdb
          • dap syncdb
          • dap dropdb
      • Client Library
        • Examples
        • Reference
      • Release Notes
      • Status
    • DataSync
      • Interop API
      • Interop Data API
      • Grades Exchange API
      • OneRoster API
      • Platform API
    • Instructure Media
      • API Reference
        • Captions
        • Collection
        • Courses
        • Group
        • Insights
        • Media
        • Media Upload
        • Ping
        • Professional Captioning
        • Tags
        • Transfer Media
        • User
    • Quizzes
      • Quiz API
Powered by GitBook

Copyright ยฉ 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.

On this page

Was this helpful?

  1. Services
  2. Instructure Media
  3. API Reference

Media Upload

PreviousMediaNextPing

Last updated 23 days ago

Was this helpful?

  • POSTCreate a new media in the specified collection from an existing file accessible by URL
  • POSTCreate a new media in "My Uploads" or specified collection from an existing file accessible by URL
  • POSTGenerate a URL to which a new media can be uploaded
  • POSTComplete a 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
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
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
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
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"
  }
}