API task creation

You can create tasks either one at a time, using the task creation endpoint, or in batches, with the create batch endpoint, with the latter being preferred.

If you are using the one at a time task creation endpoint and the task you are creating requires background processing, you need to provide a creation callback URL, through which you will be notified when the background task creation completes.

The create batch endpoint always creates tasks in a background process, but you do not need to provide a creation callback. The result of calling that endpoint includes a batch id that you can use to query the status of your batch, as well as task ids of the tasks to be created, which you can use to get the status of the tasks when the batch creation has completed.

Whether you are creating tasks one at a time or in batches, it is useful to know the task creation schema, so you know the format of the task input data you need to pass to the Sama Platform API. You can get that schema in JSON schema format from the creation JSON schema endpoint.

Task creation callback

If your project requires it or you chose to and arranged with your Sama Project Manager to receive task create responses asynchronously during the project setup step, a successful post will return a unique ID for the task that you can use to identify and track the progress of the task, along with an indicator that the task has been enqueued for creation.

Sama Platform HTTP request

When asynchronous task creation is enabled, the Sama Platform will post a request to the creation callback URL when a task has been created. Note that the URLs corresponding to any inputs marked to have their assets copied on task creation will have been replaced with URLs to the newly copied images now in Sama's own storage.

Method: POST

Header: Content-Type: application/json

URL: creation callback url defined during project set up

Authentication: Callbacks can be authenticated in one of the following ways:

basic http auth (specify a username/password)
access_key (specify an access_key in the callback URL)
token based (specify a token in an X-Auth-Token header)
HMAC-SHA-256 (specify the X-wsm-date and signed Authorization header)

Body: Example callback payload for Image with a Caption task.

{
  "task": {
    "id": "51e77305ff1d8131a4000011",
    "project_id": 117,
    "created_at": "20130715T04:45:57",
    "state": "completed",
    "batch_id": 1,
    "client_batch_id": "abc",
    "data": {
      "img": "http://samasource-storage-server.com/path/to/image/logo.png",
      "caption": "SamaLogo"
    },
    "answers": {}
  }
}

Callback HTTP response

Success

The Sama Platform will expect an appropriate response upon a successful post to the creation callback URL.

Code: 200..299

Body: Not required

Failure

Any response code other than 2xx will be treated as a failed attempt to reach the callback. The Sama Platform will retry posting a given payload to the callback a total of five times, after which the callback will be considered unreachable and the Sama Platform will no longer attempt to post the failed payload to the callback.