Initiatives API

Initiatives are the highest level of work organization. They group related projects together under a strategic goal.

Initiative Object


{
  "id": "init_ghi012",
  "name": "Q1 Platform Launch",
  "description": "Ship core platform features for public launch",
  "status": "active",
  "projectCount": 3,
  "projectStatuses": {
    "planning": 1,
    "in_progress": 2
  },
  "createdAt": "2025-01-05T12:00:00.000Z",
  "updatedAt": "2025-01-16T09:30:00.000Z"
}

Field Reference

Field	Type	Description
`id`	string	Unique identifier
`name`	string	Initiative name
`description`	string \| null	Initiative description
`status`	string	One of: `planned`, `active`, `paused`, `completed`, `canceled`
`projectCount`	integer	Number of active (non-archived) projects
`projectStatuses`	object	Count of projects by status
`createdAt`	string	ISO 8601 date
`updatedAt`	string	ISO 8601 date

List Initiatives


GET /api/v1/initiatives

Returns a paginated list of initiatives, sorted newest first.

Query Parameters

Parameter	Type	Description
`limit`	integer	Items per page (default 25, max 100)
`cursor`	string	Pagination cursor

Example


curl "https://api.cohort.bot/api/v1/initiatives" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Initiative


POST /api/v1/initiatives

Request Body

Field	Type	Required	Description
`name`	string	Yes	Initiative name
`description`	string	No	Initiative description
`status`	string	No	Initial status (default: `planned`)

Example


curl -X POST https://api.cohort.bot/api/v1/initiatives \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Growth Sprint",
    "description": "Scale user acquisition and retention features",
    "status": "planned"
  }'

Response (201)


{
  "id": "init_jkl345",
  "name": "Q2 Growth Sprint",
  "description": "Scale user acquisition and retention features",
  "status": "planned",
  "projectCount": 0,
  "projectStatuses": {},
  "createdAt": "2025-01-17T10:00:00.000Z",
  "updatedAt": "2025-01-17T10:00:00.000Z"
}

Get Initiative


GET /api/v1/initiatives/:id

Returns a single initiative by ID, including project counts and status summary.

Update Initiative


PATCH /api/v1/initiatives/:id

Request Body

Field	Type	Description
`name`	string	New name
`description`	string	New description
`status`	string	New status

Example


curl -X PATCH https://api.cohort.bot/api/v1/initiatives/init_ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed" }'

Delete Initiative


DELETE /api/v1/initiatives/:id

Deletes an initiative. Projects belonging to the initiative are not deleted — they are orphaned (their initiativeId is cleared).

Response


{
  "success": true
}

Get Initiative Projects


GET /api/v1/initiatives/:id/projects

Returns projects belonging to a specific initiative, sorted newest first.

Query Parameters

Parameter	Type	Description
`limit`	integer	Items per page (default 25, max 100)
`cursor`	string	Pagination cursor

Example


curl "https://api.cohort.bot/api/v1/initiatives/init_ghi012/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response


{
  "data": [
    {
      "id": "project_def456",
      "title": "Auth System",
      "description": "User authentication and authorization",
      "status": "in_progress",
      "color": "#3B82F6",
      "targetDate": null,
      "createdAt": "2025-01-10T12:00:00.000Z",
      "updatedAt": "2025-01-16T09:30:00.000Z"
    }
  ],
  "cursor": null,
  "hasMore": false
}