CloudFactory Platform API V3 (Deprecated)

(This is the older version of the Platform API and will no longer be available after December 25, 2017. The documentation for the latest version of the API is available here)

The Platform API allows you to programmatically send work into and receive results from the Platform.

Overview

Once you have your production line ready, you can use the Platform API to send units into the platform for processing. When the units are processed, the platform can post the results back to the callback URL you provided.

All API access is over HTTPS and the root endpoint is: 

    https://api.cloudfactory.com

The data is sent and received as JSON.

Authentication

All API requests are authenticated using HTTP Basic Authentication. The username and password can be found in your setting page.

Most HTTP libraries allow username and password to be supplied directly in the URL. Thus, your request should be posted to: 

    https://username:password@api.cloudfactory.com

Sending Units

You can send a single unit or a batch of units into a production line.

POST /v3/tasks

Request

Name Description
template_id Required.The unique identifier of the production line. You can find it in your production line setting page.
callback_url Optional.The URL to which the results are posted after the units are processed in the Platform.
resources Required.An array of objects. Each object represents an unit to be processed and should contain the input for the unit as key/value pairs. The object can have an optional key identifier. 
[{
 "identifier" : "<Unique identifier for this item>",
 "<input-key-1>" : "<input-value-1>",
 "<input-key-2>" : "<input-value-2>"

}, {
 "identifier" : "<Unique identifier for this item>",
 "<input-key-1>" : "<input-value-1>",
 "<input-key-2>" : "<input-value-1>"
}]

Example

{
   "template_id":"M4tCqxaL5tYou",
   "callback_url":"https://username:password@api.yourdomain.com/v2/result",
   "resources":[
      {
         "identifier":"0000001",
         "image_url":"http://yourdomain.com/assets/image_0000001.png",
         "company":"Microsoft"
      },
      {
         "identifier":"0000002",
         "image_url":"http://yourdomain.com/assets/image_0000002.png",
         "company":"Google"
      }
   ]
}

Response

Name Description
template_id The unique identifier of the production line.
task_id The unique identifier for the batch of units posted.
status The status of the units posted. Usually the value is In-Progress.

Example

{
 "template_id": "M4tCqxaL5tYou",
 "task_id": "E7gVrtVQJx",
 "status": "In-Progress",
 "started_at": "2015-09-17T07:36:05Z"
}

Receiving Results

Once the units in a batch (called production run) have been processed in the Platform, they are posted back to the callback URL provided for the batch.

Name Description
task_id The unique identifier of the batch of units.
started_at The time the units were sent into the Platform. The format used is YYYY-MM-DD HH:TT:SS UTC.
completed_at The time the results were completed in the Platform. The format used is YYYY-MM-DD HH:TT:SS UTC.
status The status of the batch. Usually the value is Completed. Please note that this status is for overall batch. In order to find the status of an individual unit, look inside the result of the unit.
resources An array of objects. Each object contains the result for a unit. If you had provided an identifier for a unit when sending it to the platform, it will be included in the result for that unit. The result object for each unit also contain an object called extra that contains metadata about the corresponding unit. For example, status key inside `extra' contains the status of the unit. The possible values are Completed, Flagged, and Aborted. Completed signifies that the units was successfully completed. Flagged indicates that the unit could not be completed for some reasons. Aborted indicates that the unit was aborted by the owner of the line before it could be processed.

Example

{
   "task_id":"E7gVrtVQJx",
   "started_at":"2015-09-17 07:36:05 UTC",
   "completed_at":"2015-09-17 07:40:02 UTC",
   "status":"Completed",
   "resources":[
      {
         "identifier":"0000001",
         "image_url":"http://yourdomain.com/assets/image_0000001.png",
         "company":"Microsoft",
         "location":"USA",
         "extra":{
            "status":"Completed"
         }
      },
      {
         "identifier":"0000002",
         "image_url":"http://yourdomain.com/assets/image_0000002.png",
         "company":"Google",
         "extra":{
            "status":"Flagged"
         }
      }
   ]
}

You can also receive the above response by sending the following request:

GET /v3/tasks/{task_id}

The task_id is the id of the batch of units that were sent to the Platform.

Please note that there are a few differences between the format of result posted to callback URL and fetched directly from the Platform.

The difference exists purely to maintain backward compatibility and has been eliminated in the API V4. Here is the format of result when it directly polled from the Platform:

{
   "task_id":"E7gVrtVQJx",
   "started_at":"2015-09-17T07:36:05Z",
   "finished_at":"2015-09-17T07:40:02Z",
   "status":"Completed",
   "resources":[
      {
         "identifier":"0000001",
         "image_url":"http://yourdomain.com/assets/image_0000001.png",
         "company":"Microsoft",
         "location":"USA",
         "extra":{
            "status":"Completed"
         }
      },
      {
         "identifier":"0000002",
         "image_url":"http://yourdomain.com/assets/image_0000002.png",
         "company":"Google",
         "extra":{
            "status":"Flagged"
         }
      }
   ]
}

Error Handling

If an error occurs during a request, the platform will send you a response with the appropriate error code and a description as part of the body.

Example

{
 "status": 103,
 "error": "Body is invalid."
}
Code Description HTTP Status
100 You don't own that Task. 400
101 Insufficient funds. 400
102 Data is invalid. 400
103 Body is invalid. 400
104 Internal Error. 500
105 Test is invalid. 400
106 Test answers are invalid. 400
107 No resources were passed. 400
108 Template not found. 400
109 Task not found. 400
110 No credit card on file. 400
111 Assignment not found. 404
401 Unauthorized access. 401
500 Internal Error. 500