API Reference

General notes

All requests are done over SSL.

All strings must be UTF-8 encoded.

POST requests parameters are passed in JSON-encoded bodies.

All dates are in ISO8601 format.

Authentication

Requests that create tasks such as /v1/create require authentication. There are two methods to authenticate requests:

Secret key

You can add your secret key to requests parameters, here for example for the /v1/create method:

{
    "secret": "123456",
    "tasks": {
        "task_name": "image.info",
        "url": "http://files.com/image.jpg"
    }
}

The secret key can also be passed via the Authorization header. The key should be prefixed by the string Secret, with whitespace separating the two strings:

Authorization: Secret 123456

This kind of authentication should only be used for server to server requests.

Api key + referrer

As for Secret key authentication, the api key can be passed in the request parameters or the Authorization header:

  • in request parameters:

    {
    "api_key": "654321",
    "tasks": {
        "task_name": "image.info",
        "url": "http://files.com/image.jpg"
    }
}

  • in the Authorization header:

    Authorization: Api-Key 654321

The Referrer header of the request must also be in your account’s whitelist. This kind of authentication is what you should use in your javascript code.

HTTP Status codes

200
Operation was successful.
400

Invalid request parameters. The response body contains a description of the errors, for example if you forgot the tasks parameter in a /v1/create request:

{
    "status": "error",
    "errors": [
        {
            "name": "tasks",
            "location": "body",
            "description": "tasks is missing"
        }
    ]
}
401
Invalid credentials, or account limits reached.

Tasks definitions

Task are defined by objects with at least a task_name key. Other keys contain the task parameters. Here is an example of a image.info task definition, which takes an url parameter:

{"task_name": "image.info", "url": "http://files.com/image.jpg"}

Tasks statuses format

Tasks statuses are objects of the form:

{
    "status": "executing",
    "key": "5OYA5JQVFIAHYOMLQG5QV3U33M",
    "progress": 90,
    "events": {
        "started": "2013-04-03T15:47:27.707526+00:00",
        "queued": "2013-04-03T15:47:27.703674+00:00"
    }
}

Here are the descriptions of the keys:

  • status: the current step of the task in the execution pipeline, one of “queued”, “executing, “success” or “error”

  • key: the server-side key used to identify the task

  • progress: a value representing task progress; its type depends on the task and could be anything that is JSON-encodable

  • events: an object containing chronological events of the task:
    • queued: date at which the task was queued
    • started: date at which the task has been attributed to a worker
    • completed: completion date of the task

Tasks results (with a status “success” or “error”) also contain an additional result key, containing the task result for successful tasks, or the details of the error.

Error details can be a simple string, or an object for parameters or result validation errors. Here is an example error status where a required field named “url” was omitted:

{
    "status": "error",
    "progress": null,
    "events": {
        "completed": "2013-09-20T12:56:49.385937+00:00",
        "queued": "2013-09-20T12:56:49.369911+00:00"
    },
    "key": "QJZTXA3LNZKQ6X4RPGQ5EHRSMI",
    "result": {
        "parameters": {
            "url": [
                "this field is required"
            ]
        }
    }
}

Tasks results

Warning

Tasks results are ephemeral!

Once created tasks statuses and tasks output files will be available for about one week. After that period, accessing a status or an output file will return a 404.

Tasks output files are designed to be downloaded and then served by your means.

API Methods

POST /v1/create

Queue one or more tasks and return a list of tasks status.

Here is an example request creating two tasks:

{
    "tasks": [
        {"task_name": "image.info", "url": "http://files.com/image.jpg"},
        {"task_name": "image.thumb", "url": "http://files.com/image.jpg"}
    ]
}
Query params:

tasks – a list containing the definitions of the tasks to execute. The method also accepts a single task definition for convenience.
Opt. params:

block – a boolean indicating if the call should return immediately with the current status of the tasks, or wait for all tasks to complete and return their final status.
Response:

a list of task statuses:

[
    {
        "status": "queued",
        "events": {"queued": "2013-04-03T15:47:27.703674+00:00"},
        "key": "6GRQ3H5EHU7GXUTIOSS2GUDPGQ"
    },
    {
        "status": "queued",
        "events": {"queued": "2013-04-03T15:47:27.703717+00:00"},
        "key": "5OYA5JQVFIAHYOMLQG5QV3U33M"
    }
]
GET /v1/create_file/{filename}

This is the GET version of tasks_file_post, allowing to create a task, and redirect to one of its output files by using GET semantics.

It can be useful for cases where you want to use directly the result of a task but can’t issue a POST. For example you could create a thumbnail directly in an image tag:

<img src="https://dragon.stupeflix.com/v1/create_file/cat.jpg?task_name=image.thumb&url=http://foo.com/cat.jpg" />
Path arguments:

filename – used to select the desired file, for tasks that output multiple files. Can be omited for tasks that output a single file.
Query params:
  • task_name – task name.
  • * – remaining querystring parameters are the parameters of the task.
Response:

returns the same responses as create_file_post.
GET /v1/status

Query the status of one or more tasks.

Example request:

https://dragon.stupeflix.com/v1/status?tasks=6GRQ3H5EHU7GXUTIOSS2GUDPGQ&tasks=5OYA5JQVFIAHYOMLQG5QV3U33M&block=true
Query params:
  • tasks – one or more tasks keys.
  • block – a boolean indicating if the call should return immediately with the current status of the task, or wait for all tasks to complete and return their final status.
Response:

a list of task statuses, see create for a response example.
POST /v1/status

Same as status but using POST semantics. Usefull when there are too much tasks to query and the querystring size limit is reached.

GET /v1/status_stream

Get status streams of one or more tasks.

Example request:

https://dragon.stupeflix.com/v1/stream?tasks=6GRQ3H5EHU7GXUTIOSS2GUDPGQ&tasks=5OYA5JQVFIAHYOMLQG5QV3U33M
Query params:tasks – one or more tasks keys.
Response:a stream of status updates. See create_stream for a description of the output.
POST /v1/status_stream

Same as status_stream but using POST semantics. Usefull when there are too much tasks to query and the querystring size limit is reached.

GET /v1/file/{filename}

Wait for an existing task to complete and redirect to its output.

Example request:

https://dragon.stupeflix.com/v1/file/cat.jpg?task=6GRQ3H5EHU7GXUTIOSS2GUDPGQ
Path arguments:filename – used to select the desired file, for tasks that output multiple files. Can be omited for tasks that output a single file.
Query params:task – the task key.
Response:returns the same responses as create_file_post.