How to use the API

SDKs

In general, it's recommended to use our Bitmovin API SDKs when working with our API, which is available for the most used programming languages and drastically speeds up your development.

Allowed Request Methods

  • POST - Creates a resource
  • GET - Retrieves a resource or list of resources
  • DELETE - Delete a resource

API Authentication

Every request sent to the Bitmovin API must contain your API Key. The key can be placed in the header or URL of the request. The name of the key has to be X-Api-Key. Additionally, you can change your default organization just for one request. Therefore the Organization id must be provided in the header as well

Example in Head

Header keyHeader valuerequired / optional
X-Api-Keyf916b2f5d07f4db89181e479fe099106required
X-Tenant-Org-Id397102d2-1ca2-49e2-a5ed-386fcfc0641coptional

Response Format

Every response is contained in an envelope. This means that each response has a predictable set of attributes with which you can expect to interact.

General Response Envelope

The response envelope shown below is in MSON format.

## ResponseEnvelope (object)
+ requestId: `6d84e126-d10c-4e52-bbfb-bd4c92bc8333` (string, required) - Unique correlation id
+ status (enum[string], required) - Response status information
    + Members
        + `SUCCESS`
        + `ERROR`
+ data (object, optional) - Response information
+ more (object, optional) - Additional endpoint specific information

It contains four properties:

Property NameDescriptionrequired / optional
requestIdGenerated by the API can be used for support and tracingrequired
statusStatus code that indicates if this response is an error or successrequired
dataContains the specific information returned by the service endpointoptional
moreAdditional information that could be addedoptional

Messages

Messages are used in successful and error responses to communicate details about the workflow. The Message object contains information of a single message. The type of the message could be either, INFO, ERROR, WARNING, DEBUG or TRACE. Typically you will see INFO messages and some WARNING and ERROR. DEBUG and TRACE will only be shown, if enabled for your account, or on beta features. Message also includes an optional datetime that describes the creation time of the message in our system.

## Message (object)
+ date: `2016-06-25T20:09:23.69Z` (string, optional) - Timestamp when the message occured
+ id: `cb90b80c-8867-4e3b-8479-174aa2843f62` (string, required) - Id of the message
+ type (enum[string], required) - Message type
    + Default: `INFO`
    + Members
        + `INFO` - Message is informational
        + `ERROR` - Message is an error message
        + `WARNING` - Message is an error message
        + `DEBUG` - Message is for debug
        + `TRACE` - Message is for tracing
+ text (string, required) - Message text
+ field (string, optional) - Error belongs to request field
+ links (array[Link], optional) - Links for more infos
+ more (object, optional) - Service specific information

It contains seven properties:

Property NameDescriptionrequired / optional
dateMessage creation datetimeoptional
idUnique ID of the messagerequired
typeType of the message: INFO, ERROR, WARNING, DEBUG, TRACErequired
textGeneral description of the messagerequired
fieldPresent when message is related to a specific JSON fieldoptional
linksLinks that help the user to understand or resolve the messageoptional
moreAdditional information that the service wants to provideoptional

The Link object is contained in the message and has basically two properties. The href which is an URL and the title which is the title of that URL.

## Link (object)
+ href (string, required) - URL
+ title (string, optional) - URL title

Success Response

A successful response derives from the general response envelope and further specifies the data pr