How to use the API

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

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

Example in URL

https://api.bitmovin.com/v1/encodings/?X-Api-Key=f916b2f5d07f4db89181e479fe099106

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.

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

It contains four properties:

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.

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

It contains seven properties:

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.

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

Success Response

A successful response derives from the general response envelope and further specifies the data property. The success response always has the status SUCCESS. The data property is further specified through the ResponseSuccessData object.

1## ResponseSuccess (ResponseEnvelope)
2+ status (enum[string], required) - Response status information
3    + Members
4        + `SUCCESS`
5+ data (ResponseSuccessData, optional) - Response information

The ResponseSuccessData object specifies the data object of a successful response. It contains the result from the service specific endpoint and an array of messages as defined in the messages section. These messages contain detail information about the workflow. The ResponseSuccessData object is defined by the following MSON.

1## ResponseSuccessData (object)
2+ result (object, optional) - Service specific result
3+ messages (array[Message], optional) - Service specific messages

It contains two properties:

Error Response

The error response also derives from the ResponseEnvelope but further specifies the data property. Each error response has the status ERROR.

1## ResponseError (ResponseEnvelope)
2+ status (enum[string], required) - Response status information
3    + Members
4        + `ERROR`
5+ data (ResponseErrorData, required) - Error information

The ResponseErrorData contains an error code as defined in the error code section. The response also contains a message as defined in the messages section. This message is intended to be shown to your users or in a frontend. An invidual message for a developer developerMessage that gives more details is also part of the ResponseErrorData. The developerMessage could be logged on the console or forwarded to your logging backend. Additionally the response could contain links why this error occured or how you could resolve such errors. Further detailed messages could also be part of the response, which show more details to trace error.

1## ResponseErrorData (object)
2+ code (enum[number], required) - Contains error codes as defined in error code section
3+ message (string, required) - General error message
4+ developerMessage (string, required) - Developer message
5+ links (array[Link], optional) - Link for more infos
6+ details (array[Message], optional) - Error details

ResponseErrorData contains the following properties:

• 200 OK - The request was successful (some API calls may return 201 instead).
• 201 Created - The request was successful and a resource was created.
• 202 Accepted - The request has been accepted for processing, but the processing has not been completed.
• 204 No Content - The request was successful but there is no representation to return (that is, the response is empty).
• 400 Bad Request - The request could not be understood or was missing required parameters.
• 401 Unauthorized - Authentication failed or user does not have permissions for the requested operation.
• 403 Forbidden - Access denied.
• 404 Not Found - Resource was not found.
• 405 Method Not Allowed - Requested method is not supported for the specified resource.
• 409 Conflict - Request could not be completed due to a conflict with the current state of the target resource.
• 429 Too Many Requests - Exceeded Bitmovin API limits. Pause requests, wait one minute, and try again.
• 503 Service Unavailable - The service is temporary unavailable (e.g. scheduled platform maintenance). Try again later.

1XXX General Errors

• 1000 Missing attribute or field - Required attribute/field not valid or not present
• 1001 Parameter not valid - One or more parameters are not valid
• 1002 Invalid credentials - API key is not valid
• 1003 Unauthorized - You are not authorized to access this resource
• 1004 Undefined Error - An undefined error occurred and support should be contacted
• 1005 Request URL not valid - The requested URL does not match any available API resource
• 1006 Request method not valid - The HTTP method used is not supported for this URL

5XXX Analytics Errors

• 5000 Analytics error - General analytics error
• 5001 Infrastructure error - Analytics infrastructure error

7XXX Notification Errors

• 7000 Notification Error - General notification error

8XXX Limit Exceeded Errors

• 8000 Limit exceeded error - General limit exceeded error
• 8001 Limit reached for maximum encodings per month - Your account has reached the maximum number of encodings per month
• 8003 Limit reached for maximum bytes encoded - Your account has reached the limit of bytes it is allowed to encode
• 8004 Limit reached for maximum queued VOD encodings - Your account has reached the maximum number of queued VOD encodings
• 8005 Limit reached for maximum started LIVE encodings - Your account has reached the maximum number of queued or running live encodings
• 8006 Limit reached for maximum finished VOD encodings - Your account has reached the maximum number of free encodings
• 8007 Your account has been deactivated - Please contact support

Rate limiting of the Bitmovin API is on a per access token basis.

Ensure that you inspect the HTTP headers, as they provide information about the rate limits.