Introduction

The FreeWheel Application Programming Interface (API) is a service that allows third-party tools to programmatically access and interact with data in FreeWheel. This guide outlines requirements for integrating client software with FreeWheel APIs.

Use FreeWheel APIs to:

• Retrieve, create, and update agency and advertiser information.
• Retrieve, create, and update campaign and insertion order information.
• Perform various operations on placements
• Work with MRM or RPM systems

For help with authentication, see Getting Started with Authentication.

For the complete API Reference, see API Reference.

Password Resets

Users with MRM and API access must reset their passwords every 180 days. Users with only API access must reset their passwords every 365 days. If a user's permissions change, their password expiration period updates to match their new access level.

Users with expired passwords cannot generate OAuth tokens to access FreeWheel APIs.

For more information, see the FreeWheel API Password Expiration Policy.

Resetting A Password

1. Go the User Setup page.
2. Follow the Forgot Password workflow.

📘

Note

If you can't receive emails or remember your account's password, contact your network administrator.

Updates and Breaking Changes

FreeWheel announces all API changes in Release Guides.

Deprecated/removed features are indicated in the Release Guide and marked as deprecated/removed in their respective documentation. Client tools that interpret API schema should be updated when features are deprecated/removed to avoid breaking changes.

🚧

Deprecation vs. Removal

Deprecated features still work, but no longer receive updates or support. Removed features no longer work and may result in errors when used.

AWS Gateway Migration

In order to provide API users with more functionality and greater scalability and reliability, FreeWheel has switched all Open API traffic to the Amazon Web Services (AWS) API gateway.

AWS Gateway Restrictions

The Amazon API Gateway limits character length. For more information, refer to this Amazon documentation.

Content-Encoding should not be included in HTTP request headers. Including Content-Encoding in an HTTP request will return a 415 Unsupported Media Type error and the error will not be logged. Refer to this Amazon documentation for details.

Response headers should not be copied into requests. For example, if Amazon API Gateway headers starting with x-amz- or x-amzn- are added into requests, the Amazon API Gateway will directly reject the requests without forwarding them to Freewheel.

Resources

REST Basics

In REST, everything is considered a resource. There are multiple collections of resources in FreeWheel APIs: sites, site sections, video groups, video series, etc. Each collection of resources and each individual resource can be identified by URL and can be operated upon by various methods. Here are some examples:

Some resource types form a hierarchy structure, such as sites belonging to site sections or videos belonging to video groups. Resource-specific details can be found in individual APIs' documentation.

URLs

To find the URI for a specific API, visit the API in the API Reference.

Requests

Generate an OAuth 2.0 access token to begin working with FreeWheel APIs. Tokens expires periodically and must be regenerated when expired. For details, see Getting Started with Authentication.

When designing plug-ins to FreeWheel APIs, utilize the cache and limit request frequency to 20 requests/second. Exceeding the throttling rate of twenty requests per second will result in failed calls.

Content Type

FreeWheel V3 APIs use XML. These APIs only accept HTTP requests with XML files. The API response is in XML.

FreeWheel V4 APIs use JSON , with XML support for select V4 APIs. The API response is in the same language as the request.

Media Type

The expected media type is application/json or application/xml, depending on which language the API supports. All XML bodies in the request and response should be XML 1.0. All JSON and XML requests should further be encoded as UTF-8.

The media type must be specified in two request headers:

1. Content-Type for the format of the data being sent.
2. Accept for the desired response format.

curl -X GET
     -H "Content-Type: application/json"
     -H "Accept: application/json"
     -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
     "https://api.freewheel.tv/services/v4/sites/1"

Methods

Four standard HTTP methods are supported: GET, POST, PUT, and DELETE. In cURL, the -X option specifies the request method.

To retrieve an individual resource, use the GET method. For example, to get information of a site with id = 1:

curl -X GET
     -H "Content-Type: application/json"
     -H "Accept: application/json"
     -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
    "https://api.freewheel.tv/services/v4/sites/1"

To create a new resource, use the POST method on a resource collection. The body of the request should be a JSON or XML document in the same format as one of the member resources. For example, to create a video group (using cURL's -d option to provide a request body):

curl -X POST
     -H "Content-Type: application/json"
     -H "Accept: application/json"
     -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
    "https://api.freewheel.tv/services/v4/video_groups" -d
    '{
      "name": "111",
      "external_id": "897",
      "description": "sample video group",
      "customized_metadata": {
        "label1": "value1",
        "label2": "value2"
      },
      "vod_metadata": "vod_metadata_value",
      "metadata": "6584Y65432165",
      "status": "INACTIVE"
    }'

The PUT method changes existing resources. The body of the request should be a JSON or XML document in the same format as the member resource. For example:

curl -X PUT
     -H "Content-Type: application/json"
     -H "Accept: application/json"
     -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
    "https://api.freewheel.tv/services/v4/video_groups/234" -d
    '{
      "name": "111",
      "external_id": "897",
      "description": "sample video group",
      "customized_metadata": {
        "label1": "value1",
        "label2": "value2"
      },
      "vod_metadata": "vod_metadata_value",
      "metadata": "6584Y65432165",
      "status": "INACTIVE"
    }'

📘

Note

When updating existing resources, send in all fields associated with the node that is being updated. FreeWheel overwrites existing information with the content sent through the API. Unless otherwise specified:

• Missing nodes will not update those fields' values
• Empty nodes (such as ) will clear the values for those fields
• Empty attribute nodes (such as <description/>) will clear that field's value

The DELETE method removes a resource. For example:

curl -X DELETE
  -H "Content-Type: application/json"
  -H "Accept: application/json"
  -H "Authorization: Bearer MY_OAUTH_ACCESS_TOKEN"
  "https://api.freewheel.tv/services/v4/sites/1"

📘

Note

In some cases, deleting a resource will cascade to related resources. To ensure data integrity, most resources are not allowed to be deleted, but can be deactivated.

Attributes

Creatable and updatable attributes can be included in the request body during creation and update requests, respectively. Including unsupported attributes in requests will result in errors.

Data Types

Responses

Successful POST requests and GET requests will always return the FreeWheel ID for the resources requested or created. FreeWheel recommends recording the ID of important resources for future API usage.

Successful requests have the following traits:

• A successful GET request returns a response with status code 200. The response body contains the content requested by user.
• A successful POST request (e.g., to create a new site) returns a response with status code 201. The header includes a named location with the URI of the newly-created resource. The response body contains the JSON or XML representation of the resource.
• A successful PUT request (e.g., to update an existing site) returns a response with status code 200. The header includes a named location with the URI of the updated resource. The response body contains the JSON or XML representation of the resource.
• A successful DELETE request (e.g., to delete an existing site) returns a response with status code 200 and an empty response body.

Pagination

Requests that ask for a list of resources are limited to 50 resources in the response. If the number of resources is greater than 50, then the page parameter can be used to indicate which set of 50 to return. Combine the page parameter with the per_page parameter to limit how many resources return in a single response.
For example, sending a GET request to the URL below will get the first 10 sites.

https://api.freewheel.tv/services/v4/sites?page=1&per_page=10

Response Codes

All response codes are included in the HTTP Status response header. Possible status codes in the API response include: