# API Documentation

## Add Task

<mark style="color:green;">`POST`</mark> `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](http://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.&#x20;

#### Headers

| Name   | Type   | Description                                                      |
| ------ | ------ | ---------------------------------------------------------------- |
| apikey | string | API Key for your account; available under your account settings. |

#### Request Body

| Name          | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| task          | string | <p>A key-value representation of the task you wish to have created. <br><br>Params: <br>"required\_submissions": The number of different workers you want to answer this question. Default is inherited from the project settings. <br>"reward": 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. <br>"callback\_url": 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.  <br><br>Example Task object: <br>`javascript<br>{<br>"required_submissions": 1, (optional, default is project default)<br>"reward": 0, (optional, default: 0)<br>"callback_url": "http://mywebsite.com/webhooks/cogmint", (optional)<br>"substitutions": <br>{"name": "George!", <br>"occupation": "developer"<br>}<br>}<br>` <br></p> |
| project\_uuid | string | UUID of the project you wish to add a task to. Available at the bottom of the project page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

{% tabs %}
{% tab title="200 Task successfully created." %}

```javascript
{
    "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": []    
    }
}
```

{% endtab %}

{% tab title="401 400-class errors mean something went wrong. Check message for specifics." %}

```javascript
{
    "errors": [
         {
              "field": "apikey",
              "detail": "Missing header apikey"
         }
    ]
}
```

{% endtab %}

{% tab title="422 Could not create the task due to improper or missing data." %}

```javascript
{
    "errors": [
        {
            "field": "task"
            "detail": "task is a required field"
        }
    ]
}
```

{% endtab %}
{% endtabs %}