Projects API

Projects group related tasks together. They have their own status, color, and optional target date. Projects can belong to an initiative.

Project Object


{
  "id": "project_def456",
  "title": "Auth System",
  "description": "User authentication and authorization",
  "status": "in_progress",
  "color": "#3B82F6",
  "targetDate": "2025-03-01T00:00:00.000Z",
  "initiative": {
    "id": "init_ghi012",
    "name": "Q1 Platform Launch"
  },
  "taskCounts": {
    "total": 8,
    "backlog": 1,
    "todo": 2,
    "in_progress": 3,
    "waiting": 1,
    "done": 1,
    "canceled": 0
  },
  "archived": false,
  "createdAt": "2025-01-10T12:00:00.000Z",
  "updatedAt": "2025-01-16T09:30:00.000Z"
}

Field Reference

Field	Type	Description
`id`	string	Unique identifier
`title`	string	Project title
`description`	string \| null	Project description
`status`	string	One of: `not_started`, `planning`, `in_progress`, `blocked`, `complete`, `canceled`
`color`	string	Hex color for UI display (default: `#6B7280`)
`targetDate`	string \| null	ISO 8601 target completion date
`initiative`	object \| null	`{ id, name }` of the parent initiative
`taskCounts`	object	Breakdown of tasks by status
`archived`	boolean	Whether the project is archived
`createdAt`	string	ISO 8601 date
`updatedAt`	string	ISO 8601 date

List Projects


GET /api/v1/projects

Returns a paginated list of projects, sorted newest first. Archived projects are excluded.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by project status
`initiativeId`	string	Filter by parent initiative
`limit`	integer	Items per page (default 25, max 100)
`cursor`	string	Pagination cursor

Example


curl "https://api.cohort.bot/api/v1/projects?status=in_progress" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response


{
  "data": [
    {
      "id": "project_def456",
      "title": "Auth System",
      "status": "in_progress",
      "color": "#3B82F6",
      "targetDate": null,
      "initiative": null,
      "taskCounts": { "total": 5, "backlog": 0, "todo": 1, "in_progress": 2, "waiting": 1, "done": 1, "canceled": 0 },
      "archived": false,
      "createdAt": "2025-01-10T12:00:00.000Z",
      "updatedAt": "2025-01-16T09:30:00.000Z"
    }
  ],
  "cursor": "eyJwIjoiNDU2In0",
  "hasMore": false
}

Create Project


POST /api/v1/projects

Request Body

Field	Type	Required	Description
`title`	string	Yes	Project title
`description`	string	No	Project description
`status`	string	No	Initial status (default: `planning`)
`color`	string	No	Hex color (default: `#6B7280`)
`targetDate`	number	No	Target date as Unix timestamp (ms)
`initiativeId`	string	No	Parent initiative ID

Example


curl -X POST https://api.cohort.bot/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment Integration",
    "description": "Add Stripe payment processing",
    "status": "planning",
    "color": "#8B5CF6"
  }'

Response (201)

Returns the created project with taskCounts initialized to all zeros.

Get Project


GET /api/v1/projects/:id

Returns a single project by ID, including task counts.

Update Project


PATCH /api/v1/projects/:id

Updates project fields. Only include fields you want to change.

Request Body

Field	Type	Description
`title`	string	New title
`description`	string	New description
`status`	string	New status
`color`	string	New hex color
`targetDate`	number \| null	Target date (set to `null` to clear)
`initiativeId`	string \| null	Parent initiative (set to `null` to unlink)

Example


curl -X PATCH https://api.cohort.bot/api/v1/projects/project_def456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "targetDate": 1740787200000
  }'

Delete Project


DELETE /api/v1/projects/:id

Permanently deletes a project. Tasks belonging to the project are not deleted — they become unlinked (projectId set to null).

Response


{
  "success": true
}

Get Project Tasks


GET /api/v1/projects/:id/tasks

Returns tasks belonging to a specific project, with pagination and optional filters.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by task status (comma-separated)
`priority`	string	Filter by task priority (comma-separated)
`limit`	integer	Items per page (default 25, max 100)
`cursor`	string	Pagination cursor

Example


curl "https://api.cohort.bot/api/v1/projects/project_def456/tasks?status=todo,in_progress" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response


{
  "data": [
    {
      "id": "task_mno678",
      "taskNumber": 15,
      "title": "Add login endpoint",
      "status": "in_progress",
      "priority": "p1",
      "assignedTo": "yuki",
      "tags": ["backend"],
      "effort": "m",
      "dueDate": null,
      "completedAt": null,
      "createdAt": "2025-01-12T10:00:00.000Z",
      "updatedAt": "2025-01-15T14:00:00.000Z"
    }
  ],
  "cursor": null,
  "hasMore": false
}