Create Task

This endpoint creates a task in a project and returns the generated task ID.

Endpoint

POST /v1/tasks/tasks

Authentication

Include your API key in the x-api-key header. See Authentication.

Required Scope

tasks:write

Request Body

The server does not validate field types before it writes to the database. If a required field is missing or has the wrong type, the API returns 500.

Field	Type	Required	Description
name	string	Yes	Task name. A missing name returns 500.
clientId	string	Yes	Parent client ID. The API does not check that it matches the project’s client. A missing or unknown ID returns 500.
projectId	string	Yes	Parent project ID.
description	string | null	No	Task description. Defaults to null.
isArchived	boolean	No	Archive state. Defaults to false.
autoAssign	boolean	No	Auto-assign state. Defaults to false. You can set it to true only when the parent project has autoAssign: true. Otherwise the API returns 400.
billingCategory	"BILLABLE" | "NON_BILLABLE" | null	No	Billing category. Allowed only when the parent project’s billingCategory is null. Otherwise the task inherits the project’s value, and sending this field (even null) returns 400.

Example Request Body

This example adds a task to the project from Create Project. That project has autoAssign: true and billingCategory: "BILLABLE", so the request can set autoAssign but must not send billingCategory.

{
  "name": "Task Name",
  "clientId": "client-ghi123jkl4567890",
  "projectId": "project-mno123pqr4567890",
  "description": "A brief description of the task",
  "isArchived": false,
  "autoAssign": true
}

Example Request

cURL

curl -X POST "https://api.crewsum.com/v1/tasks/tasks" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Task Name",
    "clientId": "client-ghi123jkl4567890",
    "projectId": "project-mno123pqr4567890",
    "description": "A brief description of the task",
    "isArchived": false,
    "autoAssign": true
  }'

JavaScript

const response = await fetch("https://api.crewsum.com/v1/tasks/tasks", {
  method: "POST",
  headers: {
    "x-api-key": process.env.CREWSUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Task Name",
    clientId: "client-ghi123jkl4567890",
    projectId: "project-mno123pqr4567890",
    description: "A brief description of the task",
    isArchived: false,
    autoAssign: true,
  }),
});
const result = await response.json();

HTTP

POST /v1/tasks/tasks HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>
Content-Type: application/json

{
  "name": "Task Name",
  "clientId": "client-ghi123jkl4567890",
  "projectId": "project-mno123pqr4567890",
  "description": "A brief description of the task",
  "isArchived": false,
  "autoAssign": true
}

Response

On success, the API returns HTTP 200 OK. Unlike Create Project, this endpoint does not return 201.

Example Response

{
  "message": "Successfully created task: task-pqr123stu4567890",
  "data": {
    "taskId": "task-pqr123stu4567890"
  }
}

Behavior

• The API generates the task ID in the format task-<16 hex characters>.
• Tasks created with this endpoint have isDefault: false. Each project’s default task is created with the project.
• When the parent project has a billing category, the task stores the project’s category. When the project’s category is null, the task stores the billingCategory you send, or null.
• After the task is created, Crewsum emits the tasks.created webhook event. A webhook delivery failure does not change the API response.

Error Responses

Status	Meaning
400	Cannot auto assign task while project auto assign is disabled: you sent autoAssign: true, and the parent project has autoAssign: false or does not exist.
400	Cannot set task billingCategory while project billingCategory is set: you sent billingCategory, and the parent project has a billing category or does not exist.
500	Crewsum could not create the task. The message is Error creating task. This includes a missing or unknown projectId or clientId, a missing name, and an invalid billingCategory.

Authentication and scope failures are described in Errors.

Related Webhooks

tasks.created View webhook event details.