Tasks API - Babel — Data Science Project Manager

All task endpoints are scoped to a project. You need a valid Bearer token and membership in the project to interact with tasks.

Task statuses and their workflow order:

Status	Description
`pending`	Task has been created but work has not started.
`onHold`	Task is paused, waiting on a dependency or decision.
`inProgress`	Actively being worked on.
`underReview`	Work is complete and awaiting review.
`completed`	Task has been reviewed and accepted.

Status transitions are not strictly enforced by the API — you can move a task to any status at any time.

Valid phase values

Value	Description
`business`	Business understanding
`data_understanding`	Data understanding
`data_preparation`	Data preparation
`modeling`	Modeling
`evaluation`	Evaluation
`deployment`	Deployment

These phases map to the CRISP-DM methodology used throughout Babel.

Create a task

POST /projects/:projectId/tasks Creates a new task within a project. Only the project manager can create tasks. Auth required: Yes

Path parameters

projectId

string

required

The project ID.

Request body

name

string

required

Task name.

description

string

required

Detailed description of the task.

phase

string

required

CRISP-DM phase this task belongs to. One of: business, data_understanding, data_preparation, modeling, evaluation, deployment.

assignedTo

string

User ID of the team member to assign the task to. Must be a member of the project.

estimatedHours

number

Estimated hours to complete the task.

priority

string

Task priority. One of: high, medium, low.

deadline

string

ISO 8601 deadline date, e.g. "2026-06-30T00:00:00.000Z".

Response

Returns the newly created Task object.

Example request

curl --request POST \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Collect raw transaction data",
    "description": "Pull 24 months of transaction history from the data warehouse.",
    "phase": "data_understanding",
    "priority": "high",
    "estimatedHours": 8,
    "deadline": "2026-04-15T00:00:00.000Z"
  }'

Example response

{
  "_id": "64a1f2c3b4e5d6f7a8b9c0e1",
  "name": "Collect raw transaction data",
  "description": "Pull 24 months of transaction history from the data warehouse.",
  "project": "64a1f2c3b4e5d6f7a8b9c0d1",
  "phase": "data_understanding",
  "status": "pending",
  "completed": false,
  "assignedTo": null,
  "startedAt": null,
  "finishedAt": null,
  "estimatedHours": 8,
  "priority": "high",
  "deadline": "2026-04-15T00:00:00.000Z",
  "completedBy": [],
  "notes": [],
  "createdAt": "2026-03-25T10:00:00.000Z",
  "updatedAt": "2026-03-25T10:00:00.000Z"
}

Errors

Status	Description
`400`	Missing or invalid fields.
`401`	Missing or invalid token.
`403`	Only the project manager can create tasks.
`404`	Project not found.

Get a task

GET /projects/:projectId/tasks/:taskId Returns a single task with full detail, including notes and completion history. Auth required: Yes

Path parameters

projectId

string

required

The project ID.

taskId

string

required

The task ID.

Response

_id

string

required

Unique task identifier.

name

string

required

Task name.

description

string

required

Task description.

project

string

required

ID of the parent project.

phase

string

required

CRISP-DM phase.

status

string

required

Current task status: pending, onHold, inProgress, underReview, or completed.

completed

boolean

required

Whether the task has been marked as completed.

assignedTo

object | string | null

Assigned user object or user ID, or null if unassigned.

startedAt

string | null

ISO 8601 timestamp when work started, or null.

finishedAt

string | null

ISO 8601 timestamp when work finished, or null.

estimatedHours

number | null

Estimated hours to complete.

priority

string | null

Task priority: high, medium, low, or null.

deadline

string | null

ISO 8601 deadline, or null.

completedBy

object[]

History of completion events.

Show completedBy item properties

_id

string

Entry ID.

user

object

User who performed the action.

status

string

Status set at the time of the action.

notes

Note[]

Array of notes attached to the task.

Show Note properties

_id

string

Note ID.

content

string

Note text.

createdBy

object

User who wrote the note.

task

string

Parent task ID.

createdAt

string

ISO 8601 creation timestamp.

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

ISO 8601 last-updated timestamp.

Example request

curl --request GET \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks/64a1f2c3b4e5d6f7a8b9c0e1 \
  --header 'Authorization: Bearer <token>'

Example response

{
  "_id": "64a1f2c3b4e5d6f7a8b9c0e1",
  "name": "Collect raw transaction data",
  "description": "Pull 24 months of transaction history from the data warehouse.",
  "project": "64a1f2c3b4e5d6f7a8b9c0d1",
  "phase": "data_understanding",
  "status": "inProgress",
  "completed": false,
  "assignedTo": {
    "_id": "64a1f2c3b4e5d6f7a8b9c0d2",
    "name": "Ana Torres",
    "email": "[email protected]"
  },
  "startedAt": "2026-03-26T08:00:00.000Z",
  "finishedAt": null,
  "estimatedHours": 8,
  "priority": "high",
  "deadline": "2026-04-15T00:00:00.000Z",
  "completedBy": [],
  "notes": [],
  "createdAt": "2026-03-25T10:00:00.000Z",
  "updatedAt": "2026-03-26T08:00:00.000Z"
}

Errors

Status	Description
`401`	Missing or invalid token.
`403`	You are not a member of this project.
`404`	Project or task not found.

Update a task

PUT /projects/:projectId/tasks/:taskId Updates a task’s name, description, phase, assignment, or other metadata. Auth required: Yes

Path parameters

projectId

string

required

The project ID.

taskId

string

required

The task ID.

Request body

name

string

required

Updated task name.

description

string

required

Updated task description.

phase

string

required

Updated CRISP-DM phase.

assignedTo

string

User ID of the assigned team member.

estimatedHours

number

Updated hour estimate.

priority

string

Updated priority: high, medium, or low.

deadline

string

Updated ISO 8601 deadline.

Response

Returns the updated Task object.

Example request

curl --request PUT \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks/64a1f2c3b4e5d6f7a8b9c0e1 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Collect raw transaction data",
    "description": "Pull 36 months of transaction history from the data warehouse.",
    "phase": "data_understanding",
    "priority": "high",
    "estimatedHours": 12
  }'

Errors

Status	Description
`400`	Missing or invalid fields.
`401`	Missing or invalid token.
`403`	Insufficient permissions.
`404`	Project or task not found.

Delete a task

DELETE /projects/:projectId/tasks/:taskId Permanently deletes a task and its notes. Only the project manager can delete tasks.

Deleting a task is irreversible and also removes all notes attached to it.

Auth required: Yes

Path parameters

projectId

string

required

The project ID.

taskId

string

required

The task ID.

Example request

curl --request DELETE \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks/64a1f2c3b4e5d6f7a8b9c0e1 \
  --header 'Authorization: Bearer <token>'

Example response

{
  "message": "Task deleted successfully."
}

Errors

Status	Description
`401`	Missing or invalid token.
`403`	Only the project manager can delete tasks.
`404`	Project or task not found.

Update task status

POST /projects/:projectId/tasks/:taskId/status Sets the current status of a task. Any project member can update the status of tasks assigned to them. Auth required: Yes

Path parameters

projectId

string

required

The project ID.

taskId

string

required

The task ID.

Request body

status

string

required

New status value. One of: pending, onHold, inProgress, underReview, completed.

Example request

curl --request POST \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks/64a1f2c3b4e5d6f7a8b9c0e1/status \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"status": "inProgress"}'

Example response

{
  "_id": "64a1f2c3b4e5d6f7a8b9c0e1",
  "status": "inProgress",
  "updatedAt": "2026-03-26T09:15:00.000Z"
}

Errors

Status	Description
`400`	Invalid status value.
`401`	Missing or invalid token.
`403`	You are not a member of this project.
`404`	Project or task not found.

Update task phase

PATCH /projects/:projectId/tasks/:taskId/phase Moves a task to a different CRISP-DM phase. Auth required: Yes

Path parameters

projectId

string

required

The project ID.

taskId

string

required

The task ID.

Request body

phase

string

required

New phase value. One of: business, data_understanding, data_preparation, modeling, evaluation, deployment.

Example request

curl --request PATCH \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks/64a1f2c3b4e5d6f7a8b9c0e1/phase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"phase": "modeling"}'

Example response

{
  "_id": "64a1f2c3b4e5d6f7a8b9c0e1",
  "phase": "modeling",
  "updatedAt": "2026-03-26T09:30:00.000Z"
}

Errors

Status	Description
`400`	Invalid phase value.
`401`	Missing or invalid token.
`403`	Insufficient permissions.
`404`	Project or task not found.

Toggle task completion

PATCH /projects/:projectId/tasks/:taskId/completed Toggles the completed boolean flag on a task. Each call flips the current value. Auth required: Yes

Path parameters

projectId

string

required

The project ID.

taskId

string

required

The task ID.

Example request

curl --request PATCH \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks/64a1f2c3b4e5d6f7a8b9c0e1/completed \
  --header 'Authorization: Bearer <token>'

Example response

{
  "_id": "64a1f2c3b4e5d6f7a8b9c0e1",
  "completed": true,
  "updatedAt": "2026-03-26T10:00:00.000Z"
}

Errors

Status	Description
`401`	Missing or invalid token.
`403`	You are not a member of this project.
`404`	Project or task not found.

Reassign a task

PATCH /projects/:projectId/tasks/:taskId/reassign Assigns or unassigns a task to a team member. Pass null to remove the current assignment. Auth required: Yes

Path parameters

projectId

string

required

The project ID.

taskId

string

required

The task ID.

Request body

assignedTo

string | null

required

User ID of the team member to assign the task to, or null to unassign.

Example request

curl --request PATCH \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks/64a1f2c3b4e5d6f7a8b9c0e1/reassign \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"assignedTo": "64a1f2c3b4e5d6f7a8b9c0d2"}'

Example response

{
  "_id": "64a1f2c3b4e5d6f7a8b9c0e1",
  "assignedTo": {
    "_id": "64a1f2c3b4e5d6f7a8b9c0d2",
    "name": "Ana Torres",
    "email": "[email protected]"
  },
  "updatedAt": "2026-03-26T10:30:00.000Z"
}

Errors

Status	Description
`400`	The specified user is not a member of this project.
`401`	Missing or invalid token.
`403`	Only the project manager can reassign tasks.
`404`	Project or task not found.

Create a note

POST /projects/:projectId/tasks/:taskId/notes Adds a text note to a task. Notes are visible to all project members in the task detail panel and are included in the project report for at-risk tasks. Auth required: Yes

Path parameters

projectId

string

required

The project ID.

taskId

string

required

The task ID to attach the note to.

Request body

content

string

required

The text content of the note.

Example request

curl --request POST \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks/64a1f2c3b4e5d6f7a8b9c0e1/notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"content": "Data source requires VPN access — coordinate with IT before starting."}'

Example response

{
  "_id": "64a1f2c3b4e5d6f7a8b9c0f1",
  "content": "Data source requires VPN access — coordinate with IT before starting.",
  "createdBy": {
    "_id": "64a1f2c3b4e5d6f7a8b9c0d2",
    "name": "Ana Torres",
    "email": "[email protected]"
  },
  "task": "64a1f2c3b4e5d6f7a8b9c0e1",
  "createdAt": "2026-03-25T11:00:00.000Z"
}

Errors

Status	Description
`400`	Missing note content.
`401`	Missing or invalid token.
`403`	You are not a member of this project.
`404`	Project or task not found.

Delete a note

DELETE /projects/:projectId/tasks/:taskId/notes/:noteId Permanently deletes a note from a task. Auth required: Yes

Path parameters

projectId

string

required

The project ID.

taskId

string

required

The task ID.

noteId

string

required

The note ID to delete.

Example request

curl --request DELETE \
  --url https://api.example.com/projects/64a1f2c3b4e5d6f7a8b9c0d1/tasks/64a1f2c3b4e5d6f7a8b9c0e1/notes/64a1f2c3b4e5d6f7a8b9c0f1 \
  --header 'Authorization: Bearer <token>'

Errors

Status	Description
`401`	Missing or invalid token.
`403`	You can only delete your own notes.
`404`	Note, task, or project not found.

Overview

Resources

​Valid phase values

​Create a task

​Path parameters

​Request body

​Response

​Example request

​Example response

​Errors

​Get a task

​Path parameters

​Response

​Example request

​Example response

​Errors

​Update a task

​Path parameters

​Request body

​Response

​Example request

​Errors

​Delete a task

​Path parameters

​Example request

​Example response

​Errors

​Update task status

​Path parameters

​Request body

​Example request

​Example response

​Errors

​Update task phase

​Path parameters

​Request body

​Example request

​Example response

​Errors

​Toggle task completion

​Path parameters

​Example request

​Example response

​Errors

​Reassign a task

​Path parameters

​Request body

​Example request

​Example response

​Errors

​Create a note

​Path parameters

​Request body

​Example request

​Example response

​Errors

​Delete a note

​Path parameters

​Example request

​Errors

Build docs developers (and LLMs) love

Valid phase values

Create a task

Path parameters

Request body

Response

Example request

Example response

Errors

Get a task

Path parameters

Response

Example request

Example response

Errors

Update a task

Path parameters

Request body

Response

Example request

Errors

Delete a task

Path parameters

Example request

Example response

Errors

Update task status

Path parameters

Request body

Example request

Example response

Errors

Update task phase

Path parameters

Request body

Example request

Example response

Errors

Toggle task completion

Path parameters

Example request

Example response

Errors

Reassign a task

Path parameters

Request body

Example request

Example response

Errors

Create a note

Path parameters

Request body

Example request

Example response

Errors

Delete a note

Path parameters

Example request

Errors