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 Type

Description

Exact Match

Match with a single word or with multiple words encapsulated in quotes

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 *, \, an " in a search query

Example:
   ?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

Create 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.