Getting Started with FreeWheel APIs

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 access level changes, their password expiration period updates to match their new access level.

Access LevelExpiration Policy
MRM and API accessPassword reset required every 180 days in order to maintain MRM UI and API access.
API access onlyPassword reset required every 365 days in order to maintain API access.

Resetting A Password

  1. Go the User Setup page. MRM access is not required to use this 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:

URLHTTP MethodRequest BodyAPI ResourceDescription
https://api.freewheel.tv/services/v4/sites/{site_id}GETn/asite_idGet information about site with id=1
https://api.freewheel.tv/services/v4/sitesPOSTJSON or XML bodysitesCreate a new site resource with the provided data in the request body

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

Production URL
https://api.freewheel.tv/services/v4/services

Staging URL
https://api.stg.freewheel.tv/services/v4/services

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.

Attribute TypeSupported Method
CreatablePOST
UpdatablePUT

Data Types

NameDeclaration ExampleNote
StringString
Boolean'TRUE', 'FALSE'
DatetimeDatetimeUnless otherwise specified, datetime values are expected and given in the ISO 8601 standard format "YYYY-MM-DDTHH:MM:SSZ".
DateDateUnless otherwise specified, date values are expected and given in the ISO 8601 standard format "YYYY-MM-DDZ".
Enumeration['A', 'B', 'C']
IntegerInteger
DecimalDecimalUnless otherwise specified, this indicates space for 2 decimal places, such as 3.14.
TextTextThis is for a large amount of text. CDATA can be used here.

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:

CodeResponse MessageMeaningDescription
200OKA successful GET, PUT, or DELETE request
201CreatedA successful POST request
401UnauthorizedIncorrect, missing, or invalid access credentials
403'*' not a valid key=value pair (missing equal sign) in Authorization header: '**'.ForbiddenThe Authorization header is formatted incorrectly.
403Missing Authentication TokenForbiddenThe authentication token is missing.
403User is not authorized to access this resource with an explicit denial.ForbiddenThe user does not have permission to access the API.

Contact your account team to get permission for the user.
404Not FoundThe resource requested is not available
405Method Not AllowedA request was made of a resource using a request method not supported by that resource. For example, using GET on a method which requires data to be sent by POST, or using PUT on a read-only resource.
408Request TimeoutTimeout when processing this request, usually caused by concurrent requests of exclusive access to certain resources. Retry the request.
422Unprocessable EntityInvalid resource. This error happens when the request body is invalid, or the created/updated resource is invalid.
415UNSUPPORTED MEDIA TYPEThis error may result from:

- Inserting Content-Encoding in the HTTP request header
- Incorrect formatting of Content-Type or Content-Encoding
- Incorrect formatting of data in the request body
417Unsupported HeaderThis error results from inserting "Expect: 100-continue" in the HTTP header. When using cURL, this header will be added by default. Use -H "Expect: " to explicitly remove this header.
500Internal Server ErrorAPI system error. Contact FreeWheel.

What’s Next

Get an understanding of FreeWheel's authentication workflow, then visit the API Reference for information on endpoints.