Building a Request

Most calls made to the JW Player Management API v2 (MAPI v2) consist of several components:



Base API Call

The base API call includes an HTTPS verb, base API URL, and the resource route.

POST https://api.jwplayer.com/v2/{resource}

OR

GET https://api.jwplayer.com/v2/sites/{site_id}/{resource}


Each HTTPS verb is associated with one of three types of routes: collection, object, or action routes.

Route Type Description
Collection Retrieves or appends to a list of objects
  • GET
  • POST
Object Retrieves, edits, removes, or creates a single object
  • GET
  • PATCH
  • DELETE
Action
  • PUT


Site ID

The site ID is an unique identifier for an account property. This value is sometimes referred to as the Property ID.

You can retrieve the site ID from your dashboard:

  1. Go to the Properties page.
  2. In the Property Name column, locate the name of a property.
  3. Copy the Property ID value associated with the property.

📘

Check the requirements for each API route. Not all routes require the site_id to be defined.



Query Parameters

Query parameters can only modify GET API resources calls that retrieve a collection of responses.

These collection API calls can accept the query parameters listed below.

Query Parameter Description
page Sets the page number for pagination

The first page is 1.
page_length Sets the number of items you get in the response for pagination
q Allows for querying results

See: Query Parameter q
sort Allows for sorting results by a field in either ascending or descending order

This query takes the format of: sort=field:asc|dsc. To add multiple sort parameters, separate each field name and sort order with a comma: sort=field1:asc|dsc,field2:asc|dsc.

Query Parameter q

The query parameter q provides powerful options to filter your results. The following table lists the allowable match constructions.

Match Type Description
Exact Match Match with a single word or with multiple words encapsulated in quotes

When filtering on media, JWP uses varied and changing criteria to quickly find the best results. Due to the complexities of searching longer text, value filters longer than 15 characters may not exactly match the results.

Examples:
  • ?q=title: cats
  • ?q=title: "wild cats"

Match on a custom parameter

Example: ?q=custom_param:"genre:thriller"
Special Character Use the backslash (\) to allow the special characters *, \, and " in a search query

Examples:
  • ?q=title: "\*BEST\*"
  • ?q=title: "\""
  • ?q=title: "\\"
Non-null Value Search for fields with non-null values

Example: ?q=_exists_:description
AND | OR Match with logical operators

Examples:
  • ?q=title: ( cats OR kittens )
  • ?q=title: ( cats AND dogs )
Range Define one of two types of ranges within square brackets:
  • Closed Range: Both a lower bound and upper bound are defined.
  • Open Range: Either the lower bound or upper bound is defined and the other bound is set to an asterisk (_).
Examples:
  • ?q=publish_date: [2017-01-01 TO 2017-04-01]
  • ?q=publish_date: [2017-04-01 TO _]
Inverse Match on an inverse operation

Examples:
  • ?q=title: NOT dogs
  • ?q=title: NOT "\""
  • ?q=title: NOT ( cats OR kittens )
  • ?q=title: NOT ( cats AND dogs )
  • ?q=publish_date: NOT [2017-01-01 TO 2017-04-01]
The NOT operator must precede the value of a field name. Additionally, the NOT operator cannot be used to search for null values: ?q=NOT _exists_:description.
Compound Logic Match on an inverse operation

Example:?q=( title: NOT dogs AND publish_date: [2017-01-01 TO 2017-04-01] ) OR ( title: ( cats OR kittens ) AND ( publish_date: [2017-04-01 TO *] ) )

📘

Check the requirements for each API route. Not all listing API calls accept all query parameters.



Request Body

A request body is a JSON payload that may have one or more of the following attributes: metadata, upload, and relationships.


Metadata

Metadata can be included as part of a POST or PATCH API call in order to create or modify a resource.

{
    "metadata": {
        "name": "Media Available Webhook",
        "description": "Webhook to notify me when media is ready to be published",
        "webhook_url": "https://my-endpoint.com",
        "events": ["media_available"],
        "site_ids": ["1A23bCD4"]
    }
}

Upload

A resource may require that you upload an asset to the JW Platform. Any such resource will define its upload using an upload structure in the top-level of the create request body.

{
    "metadata": {...},
    "upload": {
      "method": "direct"
    }
}

A resource may allow for different upload methods and require additional information to be defined.


Relationships

Relationships are used to define an association between two resources.

{
    "metadata": {...},
    "upload": {...},
    "relationships": {
       "protection_rule": {
         "id": "Ny05CEfj"
      }
    }
}


Headers/HTTP Headers

Since the JWP Management API v2 uses secret-based authentication, you must add a secret to the header of each API call that you make.