0
# Project Management
1

2
Project operations for creating, managing, and tracking Linear projects and initiatives, including project updates and status reporting.
3

4
## Capabilities
5

6
### Project Queries
7

8
Query individual projects or collections with filtering and pagination support.
9

10
```typescript { .api }
11
/**
12
 * Get a single project by ID
13
 * @param id - The project ID
14
 * @returns Promise resolving to the project
15
 */
16
project(id: string): LinearFetch<Project>;
17

18
/**
19
 * Get a paginated list of projects with optional filtering
20
 * @param variables - Query parameters including filters and pagination
21
 * @returns Promise resolving to a connection of projects
22
 */
23
projects(variables?: ProjectsQueryVariables): LinearFetch<ProjectConnection>;
24

25
interface ProjectsQueryVariables extends LinearConnectionVariables {
26
  /** Filter conditions for projects */
27
  filter?: ProjectFilter;
28
  /** Sort order for projects */
29
  orderBy?: PaginationOrderBy;
30
  /** Include archived projects */
31
  includeArchived?: boolean;
32
}
33

34
interface ProjectFilter {
35
  /** Filter by name */
36
  name?: StringFilter;
37
  /** Filter by slug */
38
  slugId?: StringFilter;
39
  /** Filter by state */
40
  state?: ProjectStatusFilter;
41
  /** Filter by creator */
42
  creator?: UserFilter;
43
  /** Filter by lead */
44
  lead?: NullableUserFilter;
45
  /** Filter by members */
46
  members?: UserCollectionFilter;
47
  /** Filter by teams */
48
  accessibleTeams?: TeamCollectionFilter;
49
  /** Filter by creation date */
50
  createdAt?: DateTimeFilter;
51
  /** Filter by update date */
52
  updatedAt?: DateTimeFilter;
53
  /** Filter by target date */
54
  targetDate?: NullableDateTimeFilter;
55
  /** Combine filters with AND logic */
56
  and?: ProjectFilter[];
57
  /** Combine filters with OR logic */
58
  or?: ProjectFilter[];
59
}
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { LinearClient } from "@linear/sdk";
66

67
const client = new LinearClient({ apiKey: "your-api-key" });
68

69
// Get a single project
70
const project = await client.project("project-id");
71
console.log(project.name);
72

73
// Get active projects
74
const activeProjects = await client.projects({
75
  filter: {
76
    state: { type: { eq: "started" } }
77
  }
78
});
79

80
// Get projects by lead
81
const myProjects = await client.projects({
82
  filter: {
83
    lead: { isMe: { eq: true } }
84
  }
85
});
86
```
87

88
### Project Mutations
89

90
Create, update, archive, and manage projects with comprehensive configuration options.
91

92
```typescript { .api }
93
/**
94
 * Create a new project
95
 * @param input - Project creation data
96
 * @returns Promise resolving to the creation result
97
 */
98
createProject(input: ProjectCreateInput): LinearFetch<ProjectPayload>;
99

100
/**
101
 * Update an existing project
102
 * @param id - The project ID to update
103
 * @param input - Project update data
104
 * @returns Promise resolving to the update result
105
 */
106
updateProject(id: string, input: ProjectUpdateInput): LinearFetch<ProjectPayload>;
107

108
/**
109
 * Archive a project
110
 * @param id - The project ID to archive
111
 * @returns Promise resolving to the archive result
112
 */
113
archiveProject(id: string): LinearFetch<ArchivePayload>;
114

115
/**
116
 * Unarchive a project
117
 * @param id - The project ID to unarchive
118
 * @returns Promise resolving to the unarchive result
119
 */
120
unarchiveProject(id: string): LinearFetch<ArchivePayload>;
121

122
interface ProjectCreateInput {
123
  /** Project name */
124
  name: string;
125
  /** Project description */
126
  description?: string;
127
  /** Project slug for URLs */
128
  slugId?: string;
129
  /** Project status */
130
  state?: string;
131
  /** Project lead user ID */
132
  leadId?: string;
133
  /** Member user IDs */
134
  memberIds?: string[];
135
  /** Team IDs with access */
136
  teamIds: string[];
137
  /** Target completion date */
138
  targetDate?: DateTime;
139
  /** Icon to represent the project */
140
  icon?: string;
141
  /** Color for the project */
142
  color?: string;
143
  /** Project priority */
144
  priority?: number;
145
  /** Initiative ID to associate with */
146
  initiativeId?: string;
147
}
148

149
interface ProjectUpdateInput {
150
  /** Update project name */
151
  name?: string;
152
  /** Update project description */
153
  description?: string;
154
  /** Update project slug */
155
  slugId?: string;
156
  /** Update project status */
157
  state?: string;
158
  /** Update project lead */
159
  leadId?: string;
160
  /** Update project members */
161
  memberIds?: string[];
162
  /** Update team access */
163
  teamIds?: string[];
164
  /** Update target date */
165
  targetDate?: DateTime;
166
  /** Update project icon */
167
  icon?: string;
168
  /** Update project color */
169
  color?: string;
170
  /** Update project priority */
171
  priority?: number;
172
}
173
```
174

175
**Usage Examples:**
176

177
```typescript
178
// Create a new product project
179
const newProject = await client.createProject({
180
  name: "Mobile App Redesign",
181
  description: "Complete redesign of the mobile application",
182
  state: "planned",
183
  leadId: "user-project-manager",
184
  teamIds: ["team-design", "team-mobile"],
185
  targetDate: "2024-12-01",
186
  color: "#3b82f6"
187
});
188

189
// Update project status and add team
190
const updatedProject = await client.updateProject("project-id", {
191
  state: "started",
192
  teamIds: ["team-design", "team-mobile", "team-backend"]
193
});
194
```
195

196
### Project Updates
197

198
Manage project status updates and progress reports.
199

200
```typescript { .api }
201
/**
202
 * Get project updates with filtering and pagination
203
 * @param variables - Query parameters
204
 * @returns Promise resolving to a connection of project updates
205
 */
206
projectUpdates(variables?: ProjectUpdatesQueryVariables): LinearFetch<ProjectUpdateConnection>;
207

208
/**
209
 * Create a project update
210
 * @param input - Project update creation data
211
 * @returns Promise resolving to the creation result
212
 */
213
createProjectUpdate(input: ProjectUpdateCreateInput): LinearFetch<ProjectUpdatePayload>;
214

215
/**
216
 * Update a project update
217
 * @param id - The project update ID to update
218
 * @param input - Project update modification data
219
 * @returns Promise resolving to the update result
220
 */
221
updateProjectUpdate(id: string, input: ProjectUpdateUpdateInput): LinearFetch<ProjectUpdatePayload>;
222

223
/**
224
 * Delete a project update
225
 * @param id - The project update ID to delete
226
 * @returns Promise resolving to the deletion result
227
 */
228
deleteProjectUpdate(id: string): LinearFetch<DeletePayload>;
229

230
interface ProjectUpdateCreateInput {
231
  /** Associated project ID */
232
  projectId: string;
233
  /** Update body content */
234
  body: string;
235
  /** Health status of the project */
236
  health?: ProjectUpdateHealthType;
237
  /** Update diff from previous state */
238
  diff?: string;
239
  /** Diff markdown content */
240
  diffMarkdown?: string;
241
}
242

243
enum ProjectUpdateHealthType {
244
  OnTrack = "onTrack",
245
  AtRisk = "atRisk",
246
  OffTrack = "offTrack"
247
}
248
```
249

250
### Initiative Management
251

252
Manage initiatives that group related projects and work streams.
253

254
```typescript { .api }
255
/**
256
 * Get initiatives with filtering and pagination
257
 * @param variables - Query parameters
258
 * @returns Promise resolving to a connection of initiatives
259
 */
260
initiatives(variables?: InitiativesQueryVariables): LinearFetch<InitiativeConnection>;
261

262
/**
263
 * Get a single initiative by ID
264
 * @param id - The initiative ID
265
 * @returns Promise resolving to the initiative
266
 */
267
initiative(id: string): LinearFetch<Initiative>;
268

269
/**
270
 * Create a new initiative
271
 * @param input - Initiative creation data
272
 * @returns Promise resolving to the creation result
273
 */
274
createInitiative(input: InitiativeCreateInput): LinearFetch<InitiativePayload>;
275

276
/**
277
 * Update an initiative
278
 * @param id - The initiative ID to update
279
 * @param input - Initiative update data
280
 * @returns Promise resolving to the update result
281
 */
282
updateInitiative(id: string, input: InitiativeUpdateInput): LinearFetch<InitiativePayload>;
283

284
interface InitiativeCreateInput {
285
  /** Initiative name */
286
  name: string;
287
  /** Initiative description */
288
  description?: string;
289
  /** Initiative status */
290
  status?: InitiativeStatus;
291
  /** Target completion date */
292
  targetDate?: DateTime;
293
}
294

295
enum InitiativeStatus {
296
  Planned = "planned",
297
  Started = "started",
298
  Paused = "paused",
299
  Completed = "completed",
300
  Canceled = "canceled"
301
}
302
```
303

304
## Core Project Types
305

306
```typescript { .api }
307
/** Project model representing a Linear project */
308
class Project extends Request {
309
  /** Unique project identifier */
310
  id: string;
311
  /** Project name */
312
  name: string;
313
  /** Project description */
314
  description: string;
315
  /** Project URL slug */
316
  slugId: string;
317
  /** Project state/status */
318
  state: string;
319
  /** Project progress (0-1) */
320
  progress: number;
321
  /** Project icon */
322
  icon?: string;
323
  /** Project color */
324
  color: string;
325
  /** Project priority */
326
  priority: number;
327
  /** Target completion date */
328
  targetDate?: DateTime;
329
  /** Project lead user */
330
  lead?: User;
331
  /** Project creator */
332
  creator: User;
333
  /** Project members */
334
  members: UserConnection;
335
  /** Teams with access to project */
336
  teams: TeamConnection;
337
  /** Issues in this project */
338
  issues: IssueConnection;
339
  /** Project updates */
340
  projectUpdates: ProjectUpdateConnection;
341
  /** Associated initiative */
342
  initiative?: Initiative;
343
  /** Creation timestamp */
344
  createdAt: DateTime;
345
  /** Last update timestamp */
346
  updatedAt: DateTime;
347
  /** Completion timestamp */
348
  completedAt?: DateTime;
349
  /** Archive timestamp */
350
  archivedAt?: DateTime;
351
}
352

353
/** Project update model */
354
class ProjectUpdate extends Request {
355
  /** Unique update identifier */
356
  id: string;
357
  /** Update body content */
358
  body: string;
359
  /** Project health status */
360
  health: ProjectUpdateHealthType;
361
  /** Associated project */
362
  project: Project;
363
  /** Update author */
364
  user: User;
365
  /** Update diff content */
366
  diff?: string;
367
  /** Diff in markdown format */
368
  diffMarkdown: string;
369
  /** Creation timestamp */
370
  createdAt: DateTime;
371
  /** Last update timestamp */
372
  updatedAt: DateTime;
373
}
374

375
/** Initiative model */
376
class Initiative extends Request {
377
  /** Unique initiative identifier */
378
  id: string;
379
  /** Initiative name */
380
  name: string;
381
  /** Initiative description */
382
  description?: string;
383
  /** Initiative status */
384
  status: InitiativeStatus;
385
  /** Target completion date */
386
  targetDate?: DateTime;
387
  /** Associated projects */
388
  projects: ProjectConnection;
389
  /** Creation timestamp */
390
  createdAt: DateTime;
391
  /** Last update timestamp */
392
  updatedAt: DateTime;
393
}
394

395
/** Response payload for project mutations */
396
interface ProjectPayload {
397
  /** The mutated project */
398
  project?: Project;
399
  /** Whether the mutation was successful */
400
  success: boolean;
401
  /** Last sync ID */
402
  lastSyncId: number;
403
}
404

405
/** Paginated connection of projects */
406
class ProjectConnection extends Connection<Project> {
407
  /** Projects in this page */
408
  nodes: Project[];
409
  /** Pagination information */
410
  pageInfo: PageInfo;
411
}
412
```