# Linear

> Issue tracking and project management platform for modern software development teams.

Source: https://cotera.co/docs/reference/tools/individual-tools/linear

---

**Authentication Type:** API Key\
**Description:** Issue tracking and project management platform for modern software development teams.

***

## Authentication

To get your Linear API key:

1. Login to your Linear account
2. Click on your username (top-left) and select "Workspace settings"
3. In the Settings sidebar, scroll down and click "API"
4. Add a label for your key and click "Create new API key"
5. Copy the key and store it securely (Linear won't display it again)

***

## Reference

### Lookup IDs

Look up Linear IDs by type — teams, users (assignees), labels, projects, cycles, and workflow states (statuses). Use this to resolve a human name to the ID that the Linear create/update issue tools require.

**Operation Type:** Query (Read)

**Parameters:**

* **type** `string` (required): Which kind of Linear ID to look up. Options:
  * `team` — returns IDs for use as `teamId`
  * `user` — returns IDs for use as `assigneeId`
  * `label` — returns IDs for use as `labelIds`
  * `project` — returns IDs for use as `projectId`
  * `cycle` — returns IDs for use as `cycleId`
  * `workflow-state` — returns IDs for use as `stateId` (the issue's status; statuses are team-specific)
* **teamId** `string` (nullable): Optional team ID to scope results. Only used when `type` is `workflow-state` to return statuses for a specific team. Ignored for all other types. Use null to return all workflow states across teams

**Returns:**

* **references** `array of objects`: List of matching references
  * **id** `string`: The Linear ID for use in other tools
  * **name** `string`: Human-readable name

**Example Usage:**

```json
{
  "type": "workflow-state",
  "teamId": "team_abc123"
}
```

***

## Issues

Create, update, and manage Linear issues for tracking tasks, bugs, and feature requests.

### Create Issue

Create a new Linear issue with title, description, and optional metadata like assignee, project, labels, and due date.

**Operation Type:** Mutation (Write)

**Parameters:**

* **teamId** `string` (required): The Linear team ID where the issue will be created. Use the `linear/reference/list` tool with `type: "team"` to find team IDs
* **title** `string` (required): The title/name of the issue. Should be concise and descriptive of the task or problem
* **description** `string` (nullable): Description or body text of the issue. Can include markdown formatting, details, acceptance criteria, etc. Use null if no description is needed
* **projectId** `string` (nullable): Linear project ID to associate this issue with. Use the `linear/reference/list` tool with `type: "project"` to find project IDs. Use null if not associating with a project
* **assigneeId** `string` (nullable): Linear user ID to assign this issue to. Use the `linear/reference/list` tool with `type: "user"` to find user IDs. Use null if not assigning to anyone
* **parentId** `string` (nullable): Parent issue ID to create this as a sub-issue. Use this to break down larger issues into smaller tasks. Use null if this is not a sub-issue
* **dueDate** `string` (nullable): Due date for the issue in ISO 8601 format (YYYY-MM-DD). When the issue should be completed by. Use null if no due date is needed
* **labelIds** `array of strings` (nullable): Array of Linear label IDs to categorize or tag this issue. Use the `linear/reference/list` tool with `type: "label"` to find label IDs. Use null if no labels are needed
* **cycleId** `string` (nullable): Linear cycle ID to add this issue to the current development cycle/sprint. Use the `linear/reference/list` tool with `type: "cycle"` to find cycle IDs. Use null if not adding to a cycle

**Returns:**

* **id** `string`: Linear issue ID
* **identifier** `string`: Human-readable issue identifier (e.g., "ENG-123")
* **title** `string`: Issue title
* **description** `string` (nullable): Issue description
* **priority** `number`: Issue priority level
* **createdAt** `string` (nullable): Issue creation date
* **updatedAt** `string` (nullable): Last update date

**Example Usage:**

```json
{
  "teamId": "team_abc123",
  "title": "Implement user authentication system",
  "description": "Create a comprehensive authentication system with JWT tokens, password hashing, and session management. Include login/logout functionality and password reset flow.",
  "projectId": "project_def456",
  "assigneeId": "user_ghi789",
  "parentId": null,
  "dueDate": "2024-02-15",
  "labelIds": ["label_backend", "label_security"],
  "cycleId": "cycle_jkl012"
}
```

### Update Issue

Update an existing Linear issue by modifying its properties such as title, description, assignee, priority, or status. Can also add comments to the issue during the update.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): The Linear issue ID to update. This is the unique identifier for the existing issue you want to modify
* **teamId** `string` (nullable): The Linear team ID. Use the `linear/reference/list` tool with `type: "team"` to find team IDs. Use null if not updating the team
* **title** `string` (nullable): The title/name of the issue. Use null if no title update is needed
* **description** `string` (nullable): Description or body text of the issue. Use null if no description update is needed
* **projectId** `string` (nullable): Linear project ID to associate this issue with. Use the `linear/reference/list` tool with `type: "project"` to find project IDs. Use null if not updating project association
* **assigneeId** `string` (nullable): Linear user ID to assign this issue to. Use the `linear/reference/list` tool with `type: "user"` to find user IDs. Use null if not updating assignee
* **parentId** `string` (nullable): Parent issue ID to create this as a sub-issue. Use null if not updating parent relationship
* **dueDate** `string` (nullable): Due date for the issue in ISO 8601 format (YYYY-MM-DD). Use null if not updating due date
* **labelIds** `array of strings` (nullable): Array of Linear label IDs to categorize or tag this issue. Use the `linear/reference/list` tool with `type: "label"` to find label IDs. Use null if not updating labels
* **cycleId** `string` (nullable): Linear cycle ID to add this issue to the current development cycle/sprint. Use the `linear/reference/list` tool with `type: "cycle"` to find cycle IDs. Use null if not updating cycle
* **stateId** `string` (nullable): Workflow state / status ID to set the issue's status (e.g., "In Progress", "Done"). Use the `linear/reference/list` tool with `type: "workflow-state"` (and the issue's `teamId`) to find status IDs. Use null if not updating status
* **comment** `string` (nullable): Comment to add to the issue. This will create a new comment with the provided text. Can include markdown formatting and mentions. Use null if no comment is needed
* **priority** `string` (nullable): Priority level for the issue. Options: "No Priority", "Urgent", "High", "Normal", "Low". Use null if not updating priority

**Returns:**

* **id** `string`: Linear issue ID
* **identifier** `string`: Human-readable issue identifier
* **title** `string`: Issue title
* **description** `string` (nullable): Issue description
* **priority** `number`: Issue priority level
* **createdAt** `string` (nullable): Issue creation date
* **updatedAt** `string` (nullable): Last update date
* **state** `object` (nullable): Current workflow state after the update
  * **id** `string`: State ID
  * **name** `string`: State name (e.g., "In Progress")
  * **type** `string`: State type (e.g., "started", "completed")
  * **color** `string`: State color hex code

**Example Usage:**

```json
{
  "id": "issue_xyz789",
  "teamId": null,
  "title": null,
  "description": null,
  "projectId": null,
  "assigneeId": "user_abc123",
  "parentId": null,
  "dueDate": "2024-02-20",
  "labelIds": null,
  "cycleId": null,
  "stateId": "state_inprogress456",
  "comment": "Reassigning to @john for completion. Updated due date to accommodate testing phase.",
  "priority": "High"
}
```

### Get Issue

Retrieve details of a specific Linear issue including its title, description, and current metadata.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (required): The Linear issue ID to retrieve. This will return the issue details including title, description, and other metadata

**Returns:**

* **id** `string`: Linear issue ID
* **identifier** \`string\*\*: Human-readable issue identifier
* **title** `string`: Issue title
* **description** `string` (nullable): Issue description
* **priority** `number`: Issue priority level
* **createdAt** `string` (nullable): Issue creation date
* **updatedAt** `string` (nullable): Last update date

**Example Usage:**

```json
{
  "id": "issue_xyz789"
}
```

### List Issues

Retrieve multiple Linear issues with optional filtering by team, assignee, state, priority, labels, and date ranges.

**Operation Type:** Query (Read)

**Parameters:**

* **teamId** `string` (nullable): Filter issues by Linear team ID. Use the `linear/reference/list` tool with `type: "team"` to find team IDs. Use null to search across all teams
* **assigneeId** `string` (nullable): Filter issues by assignee user ID. Use the `linear/reference/list` tool with `type: "user"` to find user IDs. Use null to include issues with any assignee
* **stateId** `string` (nullable): Filter issues by workflow state ID (e.g., "In Progress", "Done"). Use the `linear/reference/list` tool with `type: "workflow-state"` to find state IDs. Use null to include issues in any state
* **priority** `string` (nullable): Filter issues by priority. Options: "No Priority", "Urgent", "High", "Normal", "Low". Use null to include issues with any priority
* **labelIds** `array of strings` (nullable): Filter issues by label IDs. Use the `linear/reference/list` tool with `type: "label"` to find label IDs. Use null to include issues with any labels
* **createdAtGte** `string` (nullable): Filter issues created on or after this date. ISO 8601 format. Use null to not filter by creation date
* **createdAtLte** `string` (nullable): Filter issues created on or before this date. ISO 8601 format. Use null to not filter by creation date
* **updatedAtGte** `string` (nullable): Filter issues updated on or after this date. ISO 8601 format. Use null to not filter by update date
* **updatedAtLte** `string` (nullable): Filter issues updated on or before this date. ISO 8601 format. Use null to not filter by update date
* **first** `number` (nullable): Maximum number of issues to return. Use null for default limit
* **includeArchived** `boolean` (nullable): Whether to include archived issues. Use null for default behavior

**Returns:**

* **issues** `array of objects`: Array of Linear issues, each with the following fields:
  * **id** `string`: Linear issue ID
  * **identifier** `string`: Human-readable issue identifier (e.g., "ENG-123")
  * **title** `string`: Issue title
  * **description** `string` (nullable): Issue description
  * **priority** `number`: Issue priority level
  * **createdAt** `string` (nullable): Issue creation date
  * **updatedAt** `string` (nullable): Last update date
  * **state** `object` (nullable): Current workflow state
    * **id** `string`: State ID
    * **name** `string`: State name (e.g., "In Progress")
    * **type** `string`: State type (e.g., "started", "completed")
    * **color** `string`: State color hex code

**Example Usage:**

```json
{
  "teamId": "team_abc123",
  "assigneeId": null,
  "stateId": null,
  "priority": "High",
  "labelIds": ["label_backend", "label_security"],
  "createdAtGte": "2024-01-01T00:00:00.000Z",
  "createdAtLte": null,
  "updatedAtGte": null,
  "updatedAtLte": null,
  "first": 50,
  "includeArchived": false
}
```

### Add Label to Issue

Attach a label to an existing Linear issue for categorization, priority marking, or workflow organization.

**Operation Type:** Mutation (Write)

**Parameters:**

* **issueId** `string` (required): The Linear issue ID to add the label to
* **labelId** `string` (required): The Linear label ID to add to the issue

**Returns:**

* Empty object on success

**Example Usage:**

```json
{
  "issueId": "issue_xyz789",
  "labelId": "label_urgent"
}
```

### Remove Label from Issue

Remove a previously attached label from a Linear issue to update its categorization or workflow status.

**Operation Type:** Mutation (Write)

**Parameters:**

* **issueId** `string` (required): The Linear issue ID to remove the label from
* **labelId** `string` (required): The Linear label ID to remove from the issue

**Returns:**

* Empty object on success

**Example Usage:**

```json
{
  "issueId": "issue_xyz789",
  "labelId": "label_urgent"
}
```

### Attach Link to Issue

Attach a URL link to an existing Linear issue. Useful for linking documentation, external resources, or related web content to issues.

**Operation Type:** Mutation (Write)

**Parameters:**

* **issueId** `string` (required): The Linear issue ID to attach the URL to
* **url** `string` (required): The URL to attach to the issue. Should be a valid URL like "<https://example.com>"
* **title** `string` (nullable): Optional title for the link attachment. If not provided, Linear will use the page title from the URL. Use null to let Linear auto-generate the title
* **createAsUser** `string` (nullable): Create attachment as a user with the provided name. This option is only available to OAuth applications creating attachments in actor=app mode. Use null for default behavior
* **displayIconUrl** `string` (nullable): Provide an external user avatar URL. Can only be used in conjunction with the createAsUser option. Use null for default behavior

**Returns:**

* **success** `boolean`: Whether the attachment was successful
* **attachment** `object` (nullable): Attachment details
  * **id** `string`: Attachment ID
  * **url** `string`: Attached URL
  * **title** `string` (nullable): Attachment title

**Example Usage:**

```json
{
  "issueId": "issue_xyz789",
  "url": "https://docs.example.com/authentication-guide",
  "title": "Authentication Implementation Guide",
  "createAsUser": null,
  "displayIconUrl": null
}
```

***

## Common Use Cases

**Agile Development Workflow:**

* Create issues for user stories, bugs, and technical tasks with proper team assignment and project organization
* Update issue status and priority as work progresses through development cycles and sprints
* Filter and list issues by assignee, labels, and date ranges for sprint planning and progress tracking

**Project Management:**

* Organize issues under projects with parent-child relationships for feature breakdown and epic management
* Add labels for categorization by feature area, priority, or development phase
* Set due dates and track progress for milestone-based project delivery

**Team Collaboration:**

* Add comments to issues for progress updates, technical discussions, and requirement clarification
* Attach documentation links and external resources for context and reference materials
* Filter issues by team and assignee for workload distribution and individual progress tracking

**Issue Tracking and Maintenance:**

* Retrieve specific issues for detailed analysis and status updates
* Add and remove labels dynamically as issues move through different workflow states
* Track issue creation and update patterns for team productivity analysis and process improvement