3Play Media: Docs


APIv3 Responses

Our hope is that our API response patterns are as intuitive as possible. Here is a brief guide of the patterns to expect.

Object Representation

All responses should come back as JSON data. If your response appears to be HTML or other non-JSON data, check that you have correctly specified the URL by including the required root folder /v3. For example, the path http://api.3playmedia.com/v3/files will always respond with JSON data, while http://api.3playmedia.com/files is a legacy API endpoint that may respond unexpectedly.

All responses should have the following root-level signature:

Name Type Description
code Integer HTTP response code, matching the data in the response header
data String (Successful requests only) Data requested, created, or updated
error Datetime (Erroneous requests only) Error message as a Hash, containing the keys 'type', 'message', and 'items'
meta Datetime Additional information that may be helpful to a developer. Do not build to any data present in the 'meta' attribute, as it is not intended to be version-stable or machine-readable.

Known errors will respond with a helpful message to tell you what you can do to fix the error. Unknown errors will respond with code 500; these responses are logged in our system and we will do our best to address them as quickly as possible.

Example responses

  • Successful response for file data
    {"code":200,"data":[{"id":123,"name":"file123","language_id":1,"language_ids":[1],"source":"123.wav","batch_id":1,"reference_id":""}],"meta":{}}
  • Bad authentication
    {"code":401,"error":{"type":"authentication_error","message":"Invalid API key."},"meta":{}}
  • Missing required parameter
    {"code":400,"error":{"type":"parameter_error","message":"Missing required parameter: 'api_key'","items":["api_key"]},"meta":{}}
  • Unrecognized parameter for requested action
    {"code":400,"error":{"type":"parameter_error","message":"Unrecognized parameters supplied: 'bad_param'","items":["bad_param"]},"meta":{}}
  • Requested resource not found for your project
    {"code":404,"error":{"type":"not_found_error","message":"Not found"},"meta":{}}
  • Unknown error
    {"code":500,"error":{"type":"standard_error","message":"Internal server error"},"meta":{}}