API documentation

Coconut's API is a config-based API built with simplicity and flexibility in mind.
Encode your first video in less than 5 minutes.

API Reference

Creating jobs

To create a job, you just need to make a single HTTP request to the URL https://api.coconut.co/v1/job.

API version (current: 2016-05-24)

The default API version is the latest one that was available at the time you signed up. Go to your control panel to review API changes and update to the latest API version.

Authentication

You need to be authenticated with an API key using Basic Auth. The username is your API key and the password should be left blank.

HTTP Request

The HTTP request is a regular POST request with the body being the configuration.

curl https://api.coconut.co/v1/job \
-u your-api-key: \
-d '
set source = http://s3.amazonaws.com/bucket/file.avi
set webhook = http://site.com/webhook

-> mp4 = s3://access:secret@bucket/video.mp4'

We advise you to use one of our official client libraries to get started in a minute.

Response examples

When the job is succesfully submitted:

HTTP/1.1 201 Created
Server: nginx/1.4.6 (Ubuntu)
Date: Wed, 08 Oct 2014 10:25:55 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: close

{
  "id":12345,
  "status":"ok"
}


If there is an error with the request:

HTTP/1.1 400 Bad Request
Server: nginx/1.4.6 (Ubuntu)
Date: Wed, 08 Oct 2014 14:17:27 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: close

{
  "message":"The config file must specify the `source' video location and at least 1 output",
  "error_code":"config_not_valid",
  "status":"error"
}

You can find the list of error codes here.

HTTP Status codes

CodeMessage
201The job has been created successfully
400There is an error with the request. See error codes
401Unauthorized. Check if you API key is valid
403Your account has been temporarily suspended (usually 1h). You can't submit jobs anymore