# Create task

`POST /api/task`

URL: https://repsona.com/api/post-task

Creates a task in the current space.

## Request body

| name | in | type | required | description |
| --- | --- | --- | --- | --- |
| `name` | body | string | required | Task name (1 to 255 characters). |
| `parentId` | body | integer \| null | required | ID of the parent task. `null` makes the task top-level. |
| `projectId` | body | integer | required | ID of the project the task belongs to. |
| `responsibleUserId` | body | integer \| null | required | ID of the user assigned to the task. `null` leaves it unassigned. |
| `ballHoldingUserId` | body | integer \| null | required | ID of the user who currently holds the ball, meaning who needs to act next. `null` means nobody. |
| `statusId` | body | integer \| null | required | ID of the status, which must belong to the task's project. `null` clears the status. |
| `milestoneId` | body | integer \| null | required | ID of the milestone, which must belong to the task's project. `null` clears the milestone. |
| `priority` | body | integer \| null |  | Priority: `1` is High, `2` is Mid, `3` is Low. `null` clears the priority. |
| `description` | body | string \| null |  | Task description as Markdown (up to 20,000 characters). `null` clears it. |
| `startDate` | body | number \| null |  | Start date as a Unix timestamp in milliseconds. `null` clears it. |
| `dueDate` | body | number \| null |  | Due date as a Unix timestamp in milliseconds. `null` clears it. |
| `extra` | body | object \| null |  | Extra display settings. Only `color` (a color string such as `#8CC230`, or `null`) is meaningful. |
| `tags` | body | string[] |  | Names of tags to attach. Tags that do not exist yet are created. |
| `subTasks` | body | object[] |  | Subtasks to create under the new task (up to 100). They share the new task's project and status. |

## Request

```sh
curl -X POST "https://<space>.repsona.com/api/task" \
  -H "Authorization: Bearer $REPSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Write release notes",
    "parentId": null,
    "projectId": 296,
    "responsibleUserId": 1127,
    "ballHoldingUserId": 1127,
    "statusId": 195,
    "milestoneId": 38,
    "priority": 1,
    "description": "Summarize the changes in the new website for the **launch announcement**.",
    "startDate": 1794182400000,
    "dueDate": 1794528000000,
    "tags": [
      "Design"
    ],
    "subTasks": [
      {
        "name": "Collect screenshots",
        "responsibleUserId": 1127,
        "dueDate": 1794268800000
      }
    ]
  }'
```

## Responses

- 200: Task created
- 400: Invalid request payload
- 401: Authentication is required

## Example response

```json
{
  "task": {
    "id": 100442,
    "parentId": null,
    "projectId": 296,
    "responsibleUserId": 1127,
    "ballHoldingUserId": 1127,
    "statusId": 195,
    "milestoneId": 38,
    "sortOrder": null,
    "statusBoardSortOrder": null,
    "priorityBoardSortOrder": null,
    "responsibleUserBoardSortOrder": null,
    "ballHoldingUserBoardSortOrder": null,
    "milestoneBoardSortOrder": null,
    "name": "Write release notes",
    "planned": null,
    "actual": null,
    "priority": 1,
    "extra": null,
    "startDate": 1794182400000,
    "dueDate": 1794528000000,
    "createdAt": 1793662651065,
    "updatedAt": 1793662651065,
    "deletedAt": null,
    "tagIds": [
      90
    ]
  },
  "siblings": [],
  "subTasks": [
    {
      "id": 100445,
      "parentId": 100442,
      "projectId": 296,
      "responsibleUserId": 1127,
      "ballHoldingUserId": null,
      "statusId": 195,
      "milestoneId": null,
      "sortOrder": 1000,
      "statusBoardSortOrder": null,
      "priorityBoardSortOrder": null,
      "responsibleUserBoardSortOrder": null,
      "ballHoldingUserBoardSortOrder": null,
      "milestoneBoardSortOrder": null,
      "name": "Collect screenshots",
      "planned": null,
      "actual": null,
      "priority": null,
      "extra": null,
      "startDate": null,
      "dueDate": 1794268800000,
      "createdAt": 1793662651084,
      "updatedAt": 1793662651084,
      "deletedAt": null,
      "tagIds": []
    }
  ]
}
```