v1 API Documentation

Projects: Add Task

POST https://www.cogmint.com/api/v1/projects/add_task

This endpoint allows you to add new tasks to a given project. It expects you to provide the necessary parameters to create a new task under the specified project, and will post it immediately. We recommend setting up projects using www.cogmint.com to create the task templates, set project settings (such as minimum number of responses per task and other defaults) and then sharing your project's UUID with the developers to add tasks programmatically.


Headers

Field Type Description
apikey string API Key for your account; available under settings.

Body Parameters

Field Type Description
task object (map) A key-value representation of the task you wish to have created.
                  
{
  "project_uuid": "1234-123456-123456-1234",
  "required_submissions": 3,
  "reward": 25,
  "callback_url": "https://www.yourwebsite.com/incomingwebhooks",
  "substitutions": {
    "name": "Matthew",
    "key": "value"
  }
}
                  
                
Task parameters:
Field Type Description
project_uuid string UUID of the project you wish to add a task to. Available at the bottom of the project page.
required_submissions integer The number of different workers you want to answer this question. Default is inherited from the project settings.
reward integer The amount, in pennies, you're willing to offer each respondent for completing this task. Total cost for this task will be required_submissions * reward. You can cancel outstanding tasks per-project using the web UI.
callback_url string The URL to send completion event webhooks to. The webhook must be confirmed before we send any data to it. If we detect that this is a new webhook, we will attempt to confirm it before sending data.
substitutions object (map) Task specific overrides and variable substitutions. If your task is using a template with variables, you can provide the value for the variable as a key-value pair here.

Example Request

POST https://www.cogmint.com/api/v1/projects/add_task
              
{
  "task": {
    "project_uuid": "1234-123456-123456-1234",
    "required_submissions": 1,
    "reward": 50,
    "callback_url": "https://www.example.com/incomingwebhooks",
    "substitutions": {
      "name": "George",
      "occupation": "developer"
    }
  }
}
              
            

Example Response

              
{
  "data": {
    "prompt": "Please confirm George is a developer.",
    "task_uuid": "1234-123456-123456-1234",
    "reward": 0,
    "callback_url": "https://www.example.com/incomingwebhooks",
    "required_submissions": 3,
    "submission_count": 0,
    "checked_out_at": null,
    "allowed_completion_time_seconds": 3600 // default.
    "external_image_url": null
    "submissions": []
  }
}
              
            

Projects: Get Project

GET https://www.cogmint.com/api/v1/projects/:id

Retrieve a project.


Headers

Field Type Description
apikey string API Key for your account; available under settings.

URL Parameters

Field Type Description
id string ID (UUID) of the project.

Example Request

GET https://www.cogmint.com/api/v1/projects/1234-123456-123456-1234

Example Response

              
{
  "data": {
      "uuid": "1234-123456-123456-1234",
      "name": "Labeling Cars Project",
      "display_name": "Display name visible to workers",
      "display_short_description": "Please help us label cars in these images",
      "default_required_submissions": 3,
      "default_reward": 50,
      "average_outstanding_task_reward_cents": 50,
      "lifetime_payments_to_workers_cents": 15000,
      "has_published_tasks": true,
      "allowed_completion_time_seconds": 3600,
      "available_task_count": 80
    }
}
              
            

Projects: Get Annotations

GET https://www.cogmint.com/api/v1/projects/:id/annotations

For projects where the result is a series of annotations; this will return a list of annotations for all tasks that are complete. It will ignore any tasks still in progress so that it does not return partial results.


Headers

Field Type Description
apikey string API Key for your account; available under settings.

URL Parameters

Field Type Description
id string ID (UUID) of the project.

Example Request

GET https://www.cogmint.com/api/v1/projects/1234-123456-123456-1234/annotations

Example Response

              
{
  "data":[
    {
      "annotations": [
        {
          "center_x":110,
          "center_y":65,
          "height":50,
          "label":"Object",
          "width":65
        },
        {
          "center_x":518,
          "center_y":250,
          "height":55,
          "label":"Object",
          "width":70
        }
      ],
      "image": "image1.jpg",
      "task_id": "1234-1234-1234-1234"
    },
    {
      "annotations": [],
      "image": "image2.jpg",
      "task_id": "4321-4321-4321-4321"
    }
    ]
  }
              
            

Tasks: Get Task

GET https://www.cogmint.com/api/v1/tasks/:id

Returns a task by ID.


Headers

Field Type Description
apikey string API Key for your account; available under settings.

URL Parameters

Field Type Description
id string ID (UUID) of the task.

Example Request

GET https://www.cogmint.com/api/v1/tasks/5440ece7-102d-44e5-a85e-b12e5bd507fb

Example Response

              
{
  "data": {
      "allowed_completion_time_seconds": 3600,
      "callback_url": "https://callback.com",
      "checked_out_at": null,
      "external_image_url": "https://some.image.com/image.png",
      "prompt": "

Please outline the stop signs in this image

", "required_submissions": 1, "reward": 0, "submission_count": 1, "submissions": [ "object_detection" ], "task_uuid": "5440ece7-102d-44e5-a85e-b12e5bd507fb" } }

Tasks: Get Task Annotations

GET https://www.cogmint.com/api/v1/tasks/:id/annotations

Returns the 2D bounding box annotations for the task. If the task is incomplete, the annotations list will be empty until the worktask has all required submissions.

You can check whether the task has all required submissions by comparing required_submissions to submission_count.


URL Parameters

Field Type Description
id string ID (UUID) of the task.

Example Request

GET https://www.cogmint.com/api/v1/tasks/5440ece7-102d-44e5-a85e-b12e5bd507fb/annotations

Example Response

              
{
  "data": {
    "annotations": [
      {
        "center_x": 110,
        "center_y": 65,
        "height": 45,
        "label": "Object",
        "width": 63
      }
    ],
    "image": "https://your.image.host.com/151",
    "required_submissions": 1,
    "submission_count": 1,
    "task_id": "5440ece7-102d-44e5-a85e-b12e5bd507fb"
  }
}
              
            

API Errors

API Errors

Errors are inevitable; Cogmint's error messages provide clear guidance on what went wrong and how to fix it.


Common Errors

Error Example
Invalid API Key

All calls to the API require the API key to be set in the HTTP header 'apikey'. You can find both a test key and your live key in settings.

                  
{
  "errors": [
    {
      "detail": "Not a valid API Key. Put the key in the 'apikey' HTTP header. You provided: abc123123",
      "field": "root"
    }
  ]
}
                  
                
Unprocessable Entity (422)
If requesting a resource, such as a worktask, and the resource is not found
                  
{
  "errors": [
    {
      "detail": "worktask not found",
      "field": "root"
    }
  ]
}
                  
                

API Authentication

API Authentication

Authenticate calls to the Cogmint API using the HTTP header 'apikey'.

          
            apikey=yourapikeyhere
          
        

Test API Key

login to show your test API key

All API endpoints will respond with validly-shaped but otherwise meaningless data when using a test API key. Calls using test API keys do not make any changes to the database.

Live API Key

See Account API Keys