Media Items

Listing Media Items

GET /api2/media

List all media items that the current user is authorized to see.

Note

This requires the media-read permission.

Query Parameters:
 
  • type (optional) – One of audio, video, doc, image. If not specified, all types will be returned.
  • status (optional) –

    One of published, scheduled, or draft. If not specified, all statuses will be returned.

    Note

    Users will require authorization to see unpublished media items.

  • created_before (optional) – Return media items that have a created_on date prior to the given date. The date should be given as a ISO-8601 datetime in UTC.
  • created_after (optional) – Return media items that have a created_on date after the given date. The date should be given as a ISO-8601 datetime in UTC.
  • publish_before (optional) – Return media items that have a publish_on date prior to the given date. The date should be given as a ISO-8601 datetime in UTC.
  • publish_after (optional) – Return media items that have a publish_on date after the given date. The date should be given as a ISO-8601 datetime in UTC.
  • collection_id (optional) – Return media items that belong to the given collection ID. Multiple collection IDs can be provided as a comma separated list.
  • tag (optional) – Return media items that have this tag name.
  • search (optional) – Return media that match the given fulltext search terms. Set the sort parameter to relevance if you would like stonger matches to be listed first.
  • related_to (optional) – Filter for media that is “related” to the given media ID. Set the sort parameter to relevance if you would like more stongly related matches to be listed first.
  • sort (optional) – One of created_on, modified_on, publish_on, popularity, title or relevance (only applicable if the search or related_to parameters are given). Defaults to publish_on.
  • order (optional) – One of asc or desc. Defaults to asc.
  • joins (optional) – A comma separated list of links to bundle into the response. Supported values are files, thumbs and embedcode. See Joining related GET requests.
  • exclude_ids (optional) – A comma separated list of media IDs to be excluded from the media items returned.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "items": [
{
  "id": "465616",
  "type": "video",
  "status": "published",
  "title": "This is Learning Without Frontiers",
  "collection_id": "12",
  "created_on": "2012-11-09T12:02:47Z",
  "modified_on": "2013-01-18T02:38:48Z",
  "publish_on": "2012-12-07T14:29:00Z",
  "byline": "Faculty",
  "duration": 285,
  "duration_hms": "00:04:45",
  "comments_count": 1,
  "likes_count": 5
  "views_count": 17,
  "description": "<p>Learning Without Frontiers (LWF).</p>",
  "description_plain": "Learning Without Frontiers (LWF).",
  "tags": [
    "learning",
    "education",
    "school"
  ]
  "links": {
    "self": "/api2/media/465616",
    "collection": "/api2/collections/12"
    "files": "/api2/media/465616/files",
    "thumbs": "/api2/media/465616/thumbs",
    "view": "/api2/media/465616/view"
  }
}
  ],
  "links": {
    "self": "/api2/media",
    "prev": null,
    "next": "/api2/media?_p=1",
    "count": "/api2/media/count"
  }
}
GET /api2/media/count

Return a count of media items that this user is authorized to see.

This endpoint accepts all the same filter parameters as GET /api2/media.

Note

This requires the media-read permission.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "count": 251
}

Fetching a Media Item

GET /api2/media/(media_id)

Get a single media item.

Query Parameters:
 
  • joins (optional) – A comma separated list of links to bundle into the response. Supported values are files, thumbs and embedcode. See Joining related GET requests.

Note

This requires the media-read permission.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "465616",
  "type": "video",
  "status": "published",
  "title": "This is Learning Without Frontiers",
  "collection_id": "12",
  "created_on": "2012-11-09T12:02:47Z",
  "modified_on": "2013-01-18T02:38:48Z",
  "publish_on": "2012-12-07T14:29:00Z",
  "byline": "Faculty",
  "duration": 285,
  "duration_hms": "00:04:45",
  "comments_count": 1,
  "likes_count": 5
  "views_count": 17,
  "description": "<p>Learning Without Frontiers (LWF).</p>",
  "description_plain": "Learning Without Frontiers (LWF).",
  "tags": [
    "learning",
    "education",
    "school"
  ]
  "links": {
    "self": "/api2/media/465616",
    "collection": "/api2/collections/12"
    "files": "/api2/media/465616/files",
    "thumbs": "/api2/media/465616/thumbs",
    "view": "/api2/media/465616/view"
  }
}
GET /api2/media/(media_id)/view

Generate a redirect to the media view page in the MediaCore web UI.

Note

This endpoint requires no permission, however the URL that it redirects to will require the media-read permission.

Example Response:

HTTP/1.1 302 Found
Location: /media/the-arctic-light
GET /api2/media/(media_id)/embed

Generate a redirect to the embedded player page in the MediaCore web UI.

Note

This endpoint requires no permission, however the URL that it redirects to will require the media-read permission.

Example Response:

HTTP/1.1 302 Found
Location: /media/the-arctic-light/embed_player
GET /api2/media/embed-template

Get the most up-to-date template for the <iframe> embed used to embed MediaCore videos inside another page. The strings 'URL', 'WIDTH', and 'HEIGHT' should be replaced (e.g. with '/api2/media/1234/embed', '640', and '480') in order to create the final output.

Note

This endpoint requires no permissions.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "html": "<iframe src=\"URL\" width=\"WIDTH\" height=\"HEIGHT\" />"
}
GET /api2/media/(media_id)/embedcode

Generate the most up-to-date embed code for the given media item.

Note

This requires the media-read permission.

Query Parameters:
 
  • width (optional) – An optional query parameter to set the width of the desired iframe embed. Defaults to 400.
  • height (optional) – An optional query parameter to set the height of the desired iframe embed. Defaults to 225.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "html": "<iframe src=\"/media/the-arctic-light/embed_player?iframe=True\" width=\"640\" height=\"480\" />",
   "url": "/media/the-arctic-light/embed_player",
}

Adding a Media Item

POST /api2/media

Add a new media item.

The response will be 201 Created and the Location header will contain the URL for the newly created media item.

Note

This requires the media-create permission.

Json Parameters:
 
  • collection_id (conditional) – The collection to add this media item to. If My Media is enabled it will be the default collection, otherwise this field is required.
  • title (required) – The media title.
  • byline (optional) – The name to credit as the author of the media item.
  • description (optional) – The HTML description text.
  • tags (optional) – A JSON list of tag display names to be assigned to this media item.

Updating a Media Item

POST /api2/media/(media_id)

Update certain attributes of this media item.

All fields are optional; only the fields specified will be saved to the media item.

Note

This requires the media-update permission. In addition, users with the media-create permission can edit their own media items for up to 3 hours or until the media item has been published.

Json Parameters:
 
  • collection_id (optional) – The collection to add this media item to.
  • title (optional) – The media title.
  • byline (optional) – The name to credit as the author of the media item.
  • description (optional) – The HTML description text.
  • tags (optional) – A JSON list of tag display names to assign to this media item.
POST /api2/media/(media_id)/publish

Publish the media item now, or schedule it for publishing on some future date.

After calling this action, the media item’s status will be changed to published or scheduled.

Note

This requires the media-publish permission.

Json Parameters:
 
  • publish_on (optional) –

    When to schedule the media item for published. If left unspecified, the current date and time will be used, unless the media item already has a publish_on date set. The date should be given as a ISO-8601 datetime in UTC.

    Note

    Backdating is not allowed. Past dates will be ignored and the current date will be used instead.

POST /api2/media/(media_id)/unpublish

Unpublish the media item by changing its status to draft.

This will leave the publish_on attribute of the media item at its original value.

Note

This requires the media-publish permission.

POST /api2/media/(media_id)/add-tags

Add tags to the specified media item without overwriting existing tags.

Json Parameters:
 
  • tags (required) – A JSON list of tag display names to add.
POST /api2/media/(media_id)/remove-tags

Remove tags from the specified media item without modifying other existing tags.

Json Parameters:
 
  • tags (required) – A JSON list of tag display names to remove.

Deleting a Media Item

DELETE /api2/media/(media_id)

Delete a single media item.

This endpoint is idempotent; attempting to delete a media item that does not exist will return a successful response.

Note

This requires the media-delete permission. In addition, users with the media-create permission can delete their own media items for up to 3 hours or until the media item has been published.

Example Response:

HTTP/1.1 204 No Content

Previous topic

Media

Next topic

Media Files

This Page