DocsDeveloper ToolsRelease Notes
Help CenterTech BlogDashboardGet Started

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 TypeDescription
CollectionRetrieves or appends to a list of objects
GET | POST

ObjectRetrieves, edits, removes, or creates a single object
GET | PATCH | DELETE

ActionPUT


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.

📘

NOTE

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 ParameterDescription
pageSets the page number for pagination

The first page is 1.
page_lengthSets the number of items you get in the response for pagination
qAllows for querying results

See: Query Parameter q
sortAllows 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 TypeDescription
Exact MatchMatch with a single word or with multiple words encapsulated in quotes

Examples:
   ?q=title: cats
   ?q=title: "wild cats"
Special CharacterUse the backslash (\) to allow the special characters *, \, an " in a search query

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

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

Examples:
   ?q=title: ( cats OR kittens )
   ?q=title: ( cats AND dogs )
RangeDefine 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 *]
InverseMatch 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 LogicCreate compound matching logic

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 *] ) )

📘

NOTE

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 JW Platform Management API v2 uses secret-based authentication, you must add a secret to the header of each API call that you make.