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}

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:

Go to the Properties page.
In the Property Name column, locate the name of a property.
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.