0
# Issue Management
1

2
Comprehensive issue operations for creating, updating, querying, and managing Linear issues and their relationships.
3

4
## Capabilities
5

6
### Issue Queries
7

8
Query individual issues or collections of issues with filtering, sorting, and pagination.
9

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

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

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

34
interface IssueFilter {
35
  /** Filter by team */
36
  team?: NullableTeamFilter;
37
  /** Filter by assignee */
38
  assignee?: NullableUserFilter;
39
  /** Filter by creator */
40
  creator?: UserFilter;
41
  /** Filter by project */
42
  project?: NullableProjectFilter;
43
  /** Filter by state */
44
  state?: WorkflowStateFilter;
45
  /** Filter by priority */
46
  priority?: NullableNumberFilter;
47
  /** Filter by estimate */
48
  estimate?: NullableNumberFilter;
49
  /** Filter by title */
50
  title?: StringFilter;
51
  /** Filter by description */
52
  description?: NullableStringFilter;
53
  /** Filter by labels */
54
  labels?: IssueLabelCollectionFilter;
55
  /** Filter by creation date */
56
  createdAt?: DateTimeFilter;
57
  /** Filter by update date */
58
  updatedAt?: DateTimeFilter;
59
  /** Filter by due date */
60
  dueDate?: NullableDateTimeFilter;
61
  /** Filter by completion date */
62
  completedAt?: NullableDateTimeFilter;
63
  /** Filter by cycle */
64
  cycle?: NullableCycleFilter;
65
  /** Combine filters with AND logic */
66
  and?: IssueFilter[];
67
  /** Combine filters with OR logic */
68
  or?: IssueFilter[];
69
}
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { LinearClient } from "@linear/sdk";
76

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

79
// Get a single issue
80
const issue = await client.issue("issue-id");
81
console.log(issue.title);
82

83
// Get issues for a specific team
84
const teamIssues = await client.issues({
85
  first: 20,
86
  filter: {
87
    team: {
88
      key: { eq: "ENG" }
89
    }
90
  }
91
});
92

93
// Get high priority issues assigned to current user
94
const myHighPriorityIssues = await client.issues({
95
  filter: {
96
    assignee: { isMe: { eq: true } },
97
    priority: { gte: 3 }
98
  },
99
  orderBy: PaginationOrderBy.CreatedAt
100
});
101

102
// Get issues in current cycle
103
const currentCycleIssues = await client.issues({
104
  filter: {
105
    cycle: { isCurrent: { eq: true } }
106
  }
107
});
108
```
109

110
### Issue Mutations
111

112
Create, update, and delete issues with comprehensive input validation and error handling.
113

114
```typescript { .api }
115
/**
116
 * Create a new issue
117
 * @param input - Issue creation data
118
 * @returns Promise resolving to the creation result
119
 */
120
createIssue(input: IssueCreateInput): LinearFetch<IssuePayload>;
121

122
/**
123
 * Update an existing issue
124
 * @param id - The issue ID to update
125
 * @param input - Issue update data
126
 * @returns Promise resolving to the update result
127
 */
128
updateIssue(id: string, input: IssueUpdateInput): LinearFetch<IssuePayload>;
129

130
/**
131
 * Delete an issue
132
 * @param id - The issue ID to delete
133
 * @returns Promise resolving to the deletion result
134
 */
135
deleteIssue(id: string): LinearFetch<DeletePayload>;
136

137
/**
138
 * Archive an issue
139
 * @param id - The issue ID to archive
140
 * @returns Promise resolving to the archive result
141
 */
142
archiveIssue(id: string): LinearFetch<ArchivePayload>;
143

144
/**
145
 * Unarchive an issue
146
 * @param id - The issue ID to unarchive
147
 * @returns Promise resolving to the unarchive result
148
 */
149
unarchiveIssue(id: string): LinearFetch<ArchivePayload>;
150

151
interface IssueCreateInput {
152
  /** Issue title */
153
  title: string;
154
  /** Issue description in markdown */
155
  description?: string;
156
  /** Team ID where the issue belongs */
157
  teamId: string;
158
  /** User ID to assign the issue to */
159
  assigneeId?: string;
160
  /** Issue priority (1-4, where 4 is highest) */
161
  priority?: number;
162
  /** Issue estimate (story points or time) */
163
  estimate?: number;
164
  /** Project ID to associate with */
165
  projectId?: string;
166
  /** Cycle ID to associate with */
167
  cycleId?: string;
168
  /** Workflow state ID */
169
  stateId?: string;
170
  /** Label IDs to apply */
171
  labelIds?: string[];
172
  /** Parent issue ID for sub-issues */
173
  parentId?: string;
174
  /** Due date for the issue */
175
  dueDate?: DateTime;
176
  /** Template ID to create from */
177
  templateId?: string;
178
}
179

180
interface IssueUpdateInput {
181
  /** Update issue title */
182
  title?: string;
183
  /** Update issue description */
184
  description?: string;
185
  /** Update assignee */
186
  assigneeId?: string;
187
  /** Update priority */
188
  priority?: number;
189
  /** Update estimate */
190
  estimate?: number;
191
  /** Update project association */
192
  projectId?: string;
193
  /** Update cycle association */
194
  cycleId?: string;
195
  /** Update workflow state */
196
  stateId?: string;
197
  /** Update label associations */
198
  labelIds?: string[];
199
  /** Update parent issue */
200
  parentId?: string;
201
  /** Update due date */
202
  dueDate?: DateTime;
203
  /** Update subscriber list */
204
  subscriberIds?: string[];
205
}
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
// Create a new bug issue
212
const newBug = await client.createIssue({
213
  title: "Fix login validation",
214
  description: "Users can bypass email validation",
215
  teamId: "team-engineering",
216
  assigneeId: "user-john-doe",
217
  priority: 3,
218
  labelIds: ["label-bug", "label-security"]
219
});
220

221
// Update issue status and add estimate
222
const updatedIssue = await client.updateIssue("issue-id", {
223
  stateId: "state-in-progress",
224
  estimate: 5,
225
  description: "Updated description with more details"
226
});
227

228
// Archive completed issue
229
const archivedIssue = await client.archiveIssue("issue-id");
230
```
231

232
### Issue Relationships
233

234
Manage issue relationships, dependencies, and hierarchies.
235

236
```typescript { .api }
237
/**
238
 * Create a relationship between two issues
239
 * @param input - Issue relationship data
240
 * @returns Promise resolving to the relationship creation result
241
 */
242
createIssueRelation(input: IssueRelationCreateInput): LinearFetch<IssueRelationPayload>;
243

244
/**
245
 * Update an issue relationship
246
 * @param id - The relationship ID to update
247
 * @param input - Relationship update data
248
 * @returns Promise resolving to the relationship update result
249
 */
250
updateIssueRelation(id: string, input: IssueRelationUpdateInput): LinearFetch<IssueRelationPayload>;
251

252
/**
253
 * Delete an issue relationship
254
 * @param id - The relationship ID to delete
255
 * @returns Promise resolving to the deletion result
256
 */
257
deleteIssueRelation(id: string): LinearFetch<DeletePayload>;
258

259
interface IssueRelationCreateInput {
260
  /** ID of the issue that has the relation */
261
  issueId: string;
262
  /** ID of the related issue */
263
  relatedIssueId: string;
264
  /** Type of relationship */
265
  type: IssueRelationType;
266
}
267

268
enum IssueRelationType {
269
  Blocks = "blocks",
270
  BlockedBy = "blocked_by",
271
  Duplicate = "duplicate",
272
  DuplicateOf = "duplicate_of",
273
  Related = "related"
274
}
275
```
276

277
### Issue Labels
278

279
Manage issue labels for categorization and organization.
280

281
```typescript { .api }
282
/**
283
 * Get issue labels with filtering and pagination
284
 * @param variables - Query parameters
285
 * @returns Promise resolving to a connection of issue labels
286
 */
287
issueLabels(variables?: IssueLabelsQueryVariables): LinearFetch<IssueLabelConnection>;
288

289
/**
290
 * Create a new issue label
291
 * @param input - Label creation data
292
 * @returns Promise resolving to the creation result
293
 */
294
createIssueLabel(input: IssueLabelCreateInput): LinearFetch<IssueLabelPayload>;
295

296
/**
297
 * Update an issue label
298
 * @param id - The label ID to update
299
 * @param input - Label update data
300
 * @returns Promise resolving to the update result
301
 */
302
updateIssueLabel(id: string, input: IssueLabelUpdateInput): LinearFetch<IssueLabelPayload>;
303

304
interface IssueLabelCreateInput {
305
  /** Label name */
306
  name: string;
307
  /** Label description */
308
  description?: string;
309
  /** Label color hex code */
310
  color?: string;
311
  /** Team ID this label belongs to */
312
  teamId?: string;
313
}
314
```
315

316
## Core Issue Types
317

318
```typescript { .api }
319
/** Issue model representing a Linear issue */
320
class Issue extends Request {
321
  /** Unique issue identifier */
322
  id: string;
323
  /** Issue title */
324
  title: string;
325
  /** Issue description in markdown */
326
  description?: string;
327
  /** Issue number (team-specific) */
328
  number: number;
329
  /** Issue identifier (team key + number) */
330
  identifier: string;
331
  /** Issue priority (1-4) */
332
  priority: number;
333
  /** Issue estimate */
334
  estimate?: number;
335
  /** Issue URL in Linear */
336
  url: string;
337
  /** Issue state */
338
  state: WorkflowState;
339
  /** Assigned user */
340
  assignee?: User;
341
  /** Issue creator */
342
  creator?: User;
343
  /** Team the issue belongs to */
344
  team: Team;
345
  /** Associated project */
346
  project?: Project;
347
  /** Associated cycle */
348
  cycle?: Cycle;
349
  /** Issue labels */
350
  labels: IssueLabelConnection;
351
  /** Issue comments */
352
  comments: CommentConnection;
353
  /** Issue attachments */
354
  attachments: AttachmentConnection;
355
  /** Issue subscribers */
356
  subscribers: UserConnection;
357
  /** Parent issue */
358
  parent?: Issue;
359
  /** Child issues */
360
  children: IssueConnection;
361
  /** Creation timestamp */
362
  createdAt: DateTime;
363
  /** Last update timestamp */
364
  updatedAt: DateTime;
365
  /** Completion timestamp */
366
  completedAt?: DateTime;
367
  /** Due date */
368
  dueDate?: DateTime;
369
}
370

371
/** Response payload for issue mutations */
372
interface IssuePayload {
373
  /** The mutated issue */
374
  issue?: Issue;
375
  /** Whether the mutation was successful */
376
  success: boolean;
377
  /** Last sync ID */
378
  lastSyncId: number;
379
}
380

381
/** Paginated connection of issues */
382
class IssueConnection extends Connection<Issue> {
383
  /** Issues in this page */
384
  nodes: Issue[];
385
  /** Pagination information */
386
  pageInfo: PageInfo;
387
}
388
```