Retrieving Extras

Overview

Any endpoint that indicates it supports the query parameters below will return to the normal API objects with an extra object (attachment or tag) inside of each object:

NameQuery ParameterType
Attachments?with_attachments=1attachment_object
Tags?with_tags=1tag_object

The Attachments Object

To get the attachments for discussions in a given course you would use an endpoint like:

Each attachment type has a different set of fields, enumerated below:

FieldNameDescriptionTypeRequired
filesFile AttachmentsA list of file objectsfile_object
linksLink AttachmentsA list of link objectslink_object
videosVideo AttachmentsA list of video objectsvideo_object
embedsEmbed AttachmentsA list of embed objectsembed_object

File Object

A few notes about the converted_fields:

  • A converted file is a unique file from the original file. The converted file’s value is that it has been converted to a format supported by more devices. However, the value of the original file is still very important. This motivates the decision to return information about both files.
  • The converted_status will always given. The converted_status is a integer. The meanings of the numbers are as follows:
    • 1 : The file has been converted and is available
    • 2 : The file is pending conversion
    • 3 : File conversion has failed
    • 4 : Any sort of conversion attempts are inactive.
  • The converted_type will always be given. This flags what type of file Schoology abstracts and tries to convert the original file too (e.g. .flv, .mp4, .asf, .wmv, and .smi are all considered video files). The constants are as follows:
    • 1 : Video
    • 2 : Audio
    • 3 : Image
    • 4 : Document
    • 5 : Unknown
  • The only time converted file information will be given is if a file of converted_type Audio (2) or Video (1) file has been converted and is available, information about that file will be returned in the file object.
FieldNameDescriptionTypeRequired
idAttachment IDThe internal Schoology ID of the attachmentinteger
titleTitle of the attachmentTitle of the attachment, could be different from filenamestring
filenameFilenameThe name of the filestring
md5_checksumMd5 ChecksumMD5 checksum of the filestring
timestampTimestampThe timestamp of when the file was uploadedinteger
download_pathDownload PathAn API accessible URL to the file.string
extensionFile ExtensionThe extension of the file, merely a convenience field for the userstring
converted_statusConverted StatusStatus of the conversion process for this fileinteger
converted_typeConverted TypeType of file Schoology would consider this extensioninteger
converted_filenameConverted FilenameThe name of the converted filestring
converted_download_pathConverted Download PathThe download path of the converted filestring
converted_extensionConverted ExtensionThe extension of the converted filestring
converted_filesizeConverted FilesizeThe size of the converted fileinteger
converted_md5_checksumConverted MD5 ChecksumThe md5 checksum of the converted filestring
FieldNameDescriptionTypeRequired
idAttachment IDThe internal Schoology ID of the attachmentinteger
titleTitle of the attachmentTitle of the attachment, could be different from filenamestring
urlURLURL of the link attachmentstring
summarySummaryIf requested by attaching user, a small teaser from the link sitestring
faviconFaviconLink to the favicon image from the sitestring
thumbnailThumbnail imageIf request by attaching user, a thumbnail image from the link sitestring

Video Object

  • The video type is very similar to the link type. This simply denotes that this is a link to a site that Schoology handles in a special fashion. For links pointing to sites like youtube and vimeo and other video hosting sites, Schoology does some special fetching to do things like generate a thumbnail.
FieldNameDescriptionTypeRequired
idAttachment IDThe internal Schoology ID of the attachmentinteger
titleTitle of the attachmentTitle of the attachment, could be different from filenamestring
urlURLURL of the link attachmentstring
faviconFaviconLink to the favicon image from the sitestring
thumbnailThumbnail imageIf request by attaching user, a thumbnail image from the link sitestring

Embed Object

FieldNameDescriptionTypeRequired
idAttachment IDThe internal Schoology ID of the attachmentinteger
embed_codeEmbed CodeThe embed code of the embedstring

The Tags Object

Tags is the API name for the various alignment types Schoology supports such as state standards and custom learning outcomes. Users can associate or “Tag” content such as Assignments, Documents, Resources or Discussions. Endpoints that support tags will have the with_tags parameter listed as a supported query parameter.

To get the tags for discussions in a given course you would use an endpoint like:

FieldNameDescriptionTypeRequired
titleTitle of tagTitle of tagstring
descriptionDescriptionDescriptionstring
idTerm IDThe internal Schoology term IDinteger
vidVocabulary IDThe internal Schoology vocabulary ID of the taginteger