Our hope is that our API response patterns are as intuitive as possible. Here is a brief guide of the patterns to expect.
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 https://api.3playmedia.com/v3/files will always respond with JSON data, while https://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.
{"code":200,"data":[{"id":123,"name":"file123","language_id":1,"language_ids":[1],"source":"123.wav","batch_id":1,"reference_id":""}],"meta":{}}
{"code":401,"error":{"type":"authentication_error","message":"Invalid API key."},"meta":{}}
{"code":400,"error":{"type":"parameter_error","message":"Missing required parameter: 'api_key'","items":["api_key"]},"meta":{}}
{"code":400,"error":{"type":"parameter_error","message":"Unrecognized parameters supplied: 'bad_param'","items":["bad_param"]},"meta":{}}
{"code":404,"error":{"type":"not_found_error","message":"Not found"},"meta":{}}
{"code":500,"error":{"type":"standard_error","message":"Internal server error"},"meta":{}}