> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/legacy/legacy-experience/books/reference/linear.md).

# Linear

{% hint style="info" %}
The following documentation is for **Linear v1.4.0** *(BDK)*.
{% endhint %}

## Overview

Linear is a modern issue tracking and project management tool designed for software development teams. This integration allows automated issue creation, status updates, project tracking, and team workflow management. Enhance development productivity and maintain organized project tracking.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Linear**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using Personal API Key

Connect to Linear using a Personal API Key.

| Label            | Description                                            | Type        |
| ---------------- | ------------------------------------------------------ | ----------- |
| Personal API Key | Your Linear Personal API Key (starts with lin\_api\_). | `sensitive` |

## Procedures

### to add a label to a linear issue

Apply a label to a Linear issue.

**Input Concepts**

| Concept                  | Description                                                                   | Type           | Required | Default Value |
| ------------------------ | ----------------------------------------------------------------------------- | -------------- | -------- | ------------- |
| [`issue`](#linear-issue) | The issue to label.                                                           | `linear issue` | Yes      | (no default)  |
| `label`                  | The exact label name to apply. Use `get the labels` to discover valid values. | `text`         | Yes      | (no default)  |

**Output Concepts**

| Concept                   | Description                   | Type           |
| ------------------------- | ----------------------------- | -------------- |
| [`answer`](#linear-issue) | the issue: The updated issue. | `linear issue` |

**Examples**

```generic
get a linear issue by id
get the labels
add a label to the linear issue
   the label is "Bug"
```

### to add an issue to a linear cycle

Add a Linear issue to a cycle (sprint).

**Input Concepts**

| Concept                  | Description                           | Type           | Required | Default Value |
| ------------------------ | ------------------------------------- | -------------- | -------- | ------------- |
| [`issue`](#linear-issue) | The Linear issue to add.              | `linear issue` | Yes      | (no default)  |
| [`cycle`](#linear-cycle) | The Linear cycle to add the issue to. | `linear cycle` | Yes      | (no default)  |

**Output Concepts**

| Concept                   | Description                   | Type           |
| ------------------------- | ----------------------------- | -------------- |
| [`answer`](#linear-issue) | the issue: The updated issue. | `linear issue` |

**Examples**

```generic
get a linear issue by id
get the cycles of a linear team
add the linear issue to the linear cycle
   the cycle is the first cycle
```

### to create a comment on a linear issue

Post a comment on a Linear issue.

**Input Concepts**

| Concept                  | Description                     | Type           | Required | Default Value |
| ------------------------ | ------------------------------- | -------------- | -------- | ------------- |
| [`issue`](#linear-issue) | The Linear issue to comment on. | `linear issue` | Yes      | (no default)  |
| `body`                   | The text of the comment.        | `text`         | Yes      | (no default)  |

**Output Concepts**

| Concept                     | Description                       | Type             |
| --------------------------- | --------------------------------- | ---------------- |
| [`answer`](#linear-comment) | the comment: The created comment. | `linear comment` |

**Examples**

```generic
get a linear issue by id
create a comment on the linear issue
   the body is "Looking into this now."
```

### to create a linear project

Create a new project in Linear.

**Input Concepts**

| Concept                | Description                             | Type          | Required | Default Value |
| ---------------------- | --------------------------------------- | ------------- | -------- | ------------- |
| `name`                 | The project name.                       | `text`        | Yes      | (no default)  |
| [`team`](#linear-team) | The team that owns the project.         | `linear team` | Yes      | (no default)  |
| `description`          | Optional. A description of the project. | `text`        | No       | (no default)  |

**Output Concepts**

| Concept                     | Description                              | Type             |
| --------------------------- | ---------------------------------------- | ---------------- |
| [`answer`](#linear-project) | the project: The created Linear project. | `linear project` |

**Examples**

```generic
get some teams
create a linear project
   the name is "Q3 Launch"
   the team is the first team
```

### to create an issue

Create an issue in Linear.

**Input Concepts**

| Concept                | Description                                     | Type          | Required | Default Value |
| ---------------------- | ----------------------------------------------- | ------------- | -------- | ------------- |
| `title`                | The title of the issue.                         | `text`        | Yes      | (no default)  |
| `description`          | The description of the issue.                   | `text`        | Yes      | (no default)  |
| [`team`](#linear-team) | The team in which you want to create the issue. | `linear team` | Yes      | (no default)  |

**Output Concepts**

| Concept                   | Description                   | Type           |
| ------------------------- | ----------------------------- | -------------- |
| [`answer`](#linear-issue) | the issue: The created issue. | `linear issue` |

**Examples**

```generic
get some teams
use the first team as the team
create an issue
   the title is "Test Issue"
   the description is "This is a test issue"
   the team is the team
```

### to delete a linear comment

Delete a comment from a Linear issue.

**Input Concepts**

| Concept                      | Description            | Type             | Required | Default Value |
| ---------------------------- | ---------------------- | ---------------- | -------- | ------------- |
| [`comment`](#linear-comment) | The comment to delete. | `linear comment` | Yes      | (no default)  |

**Output Concepts**

| Concept  | Description                                         | Type      |
| -------- | --------------------------------------------------- | --------- |
| `answer` | Whether Linear reported the deletion as successful. | `boolean` |

**Examples**

```generic
get the comments on a linear issue
delete the first linear comment
```

### to delete an issue from linear

Delete a Linear issue.

**Input Concepts**

| Concept                  | Description                 | Type           | Required | Default Value |
| ------------------------ | --------------------------- | -------------- | -------- | ------------- |
| [`issue`](#linear-issue) | The Linear issue to delete. | `linear issue` | Yes      | (no default)  |

**Output Concepts**

| Concept  | Description                                       | Type      |
| -------- | ------------------------------------------------- | --------- |
| `answer` | Whether Linear reported the delete as successful. | `boolean` |

**Examples**

```generic
get a linear issue by id
delete the issue from linear
```

### to follow a linear issue

Subscribe the authenticated user to a Linear issue to receive notifications.

**Input Concepts**

| Concept                  | Description                | Type           | Required | Default Value |
| ------------------------ | -------------------------- | -------------- | -------- | ------------- |
| [`issue`](#linear-issue) | The issue to subscribe to. | `linear issue` | Yes      | (no default)  |

**Output Concepts**

| Concept  | Description                              | Type      |
| -------- | ---------------------------------------- | --------- |
| `answer` | Whether the subscription was successful. | `boolean` |

**Examples**

```generic
get a linear issue by id
follow the linear issue
```

### to get a linear issue by id

Fetch a single Linear issue by UUID, identifier, or issue number.

**Input Concepts**

| Concept    | Description                                                                                                                           | Type   | Required | Default Value |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | ------------- |
| `issue id` | The Linear UUID, issue identifier (for example "INT-123"), or bare issue number. Bare issue numbers must uniquely identify one issue. | `text` | Yes      | (no default)  |

**Output Concepts**

| Concept                   | Description                           | Type           |
| ------------------------- | ------------------------------------- | -------------- |
| [`answer`](#linear-issue) | the issue: The matching Linear issue. | `linear issue` |

**Examples**

```generic
get a linear issue by id
   the issue id is "INT-123"
```

### to get a linear user

Find a Linear workspace user by their display name or email address.

**Input Concepts**

| Concept      | Description                                     | Type   | Required | Default Value |
| ------------ | ----------------------------------------------- | ------ | -------- | ------------- |
| `user query` | The user's display name or email to search for. | `text` | Yes      | (no default)  |

**Output Concepts**

| Concept                  | Description                         | Type          |
| ------------------------ | ----------------------------------- | ------------- |
| [`answer`](#linear-user) | the user: The matching Linear user. | `linear user` |

**Examples**

```generic
get a linear user
   the user query is "alice@example.com"
```

### to get all linear users

List all users in the Linear workspace.

**Output Concepts**

| Concept                  | Description                 | Type          |
| ------------------------ | --------------------------- | ------------- |
| [`answer`](#linear-user) | the list of workspace users | `linear user` |

**Examples**

```generic
get all linear users
```

### to get the (comments) from a linear issue

Fetch all comments on a Linear issue.

**Input Concepts**

| Concept                  | Description                                         | Type           | Required | Default Value |
| ------------------------ | --------------------------------------------------- | -------------- | -------- | ------------- |
| [`issue`](#linear-issue) | The Linear issue whose comments should be returned. | `linear issue` | Yes      | (no default)  |

**Output Concepts**

| Concept                       | Description                       | Type             |
| ----------------------------- | --------------------------------- | ---------------- |
| [`comments`](#linear-comment) | the list of comments on the issue | `linear comment` |

**Examples**

```generic
get a linear issue by id
get the comments from the linear issue
```

### to get the (cycles) of a linear team

List all cycles (sprints) for a Linear team.

**Input Concepts**

| Concept                | Description                                      | Type          | Required | Default Value |
| ---------------------- | ------------------------------------------------ | ------------- | -------- | ------------- |
| [`team`](#linear-team) | The Linear team whose cycles should be returned. | `linear team` | Yes      | (no default)  |

**Output Concepts**

| Concept                   | Description                     | Type           |
| ------------------------- | ------------------------------- | -------------- |
| [`cycles`](#linear-cycle) | the list of cycles for the team | `linear cycle` |

**Examples**

```generic
get some teams
get the cycles of the first team
```

### to get the (issues)

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Fetch the issues matching the filters (if any).

**Input Concepts**

| Concept | Description                                                                                            | Type   | Required | Default Value |
| ------- | ------------------------------------------------------------------------------------------------------ | ------ | -------- | ------------- |
| `label` | Filter by label name (case-sensitive). Use `get the labels` to discover valid values before filtering. | `text` | No       | (no default)  |

**Output Concepts**

| Concept                   | Description        | Type           |
| ------------------------- | ------------------ | -------------- |
| [`issues`](#linear-issue) | the list of issues | `linear issue` |

**Examples**

```generic
the states are "Todo", "Backlog" and "In Progress"
get the issues whose assignee email is "someone@example.com" and whose state name is in the states
```

```generic
get the issues whose title contains "authentication"
```

```generic
get the issues whose state name is "In Progress"
```

```generic
get the labels
get the issues with label "ComplexityLow"
```

```generic
get the issues whose team name is "Integrations"
```

### to get the (labels)

Fetch all available issue label names in the workspace.

Use this before filtering issues by label: label filtering is case-sensitive, and the names returned here are the exact values to pass to `get the issues`.

**Output Concepts**

| Concept  | Description                                             | Type   |
| -------- | ------------------------------------------------------- | ------ |
| `labels` | alphabetically sorted, deduplicated list of label names | `text` |

**Examples**

```generic
get the labels
```

### to get the (notifications) from linear

Fetch notifications for the authenticated Linear user.

**Output Concepts**

| Concept                                 | Description               | Type                  |
| --------------------------------------- | ------------------------- | --------------------- |
| [`notifications`](#linear-notification) | the list of notifications | `linear notification` |

**Examples**

```generic
get the notifications from linear
```

### to get the (projects) from linear

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Fetch projects in the Linear workspace matching the filters (if any).

**Output Concepts**

| Concept                       | Description                 | Type             |
| ----------------------------- | --------------------------- | ---------------- |
| [`projects`](#linear-project) | the list of Linear projects | `linear project` |

**Examples**

```generic
get the projects from linear
```

```generic
get the projects from linear whose name is "Q3 Launch"
```

### to get the (teams)

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Fetch the teams matching the filters (if any).

**Output Concepts**

| Concept                 | Description       | Type          |
| ----------------------- | ----------------- | ------------- |
| [`teams`](#linear-team) | the list of teams | `linear team` |

**Examples**

```generic
get some teams
```

```generic
get the teams whose name is "Engineering"
```

### to get the (users) from a team

Get the users from a team.

**Input Concepts**

| Concept                | Description                                           | Type          | Required | Default Value |
| ---------------------- | ----------------------------------------------------- | ------------- | -------- | ------------- |
| [`team`](#linear-team) | The linear team from which you want to get the users. | `linear team` | Yes      | (no default)  |

**Output Concepts**

| Concept                 | Description                               | Type          |
| ----------------------- | ----------------------------------------- | ------------- |
| [`users`](#linear-user) | the users: The list of users in the team. | `linear user` |

**Examples**

```generic
get some teams
get some users from the first team
```

### to get the workflow states of a linear team

List all workflow states available in a Linear team.

**Input Concepts**

| Concept                | Description                                               | Type          | Required | Default Value |
| ---------------------- | --------------------------------------------------------- | ------------- | -------- | ------------- |
| [`team`](#linear-team) | The Linear team whose workflow states should be returned. | `linear team` | Yes      | (no default)  |

**Output Concepts**

| Concept                            | Description                 | Type                    |
| ---------------------------------- | --------------------------- | ----------------------- |
| [`answer`](#linear-workflow-state) | the list of workflow states | `linear workflow state` |

**Examples**

```generic
get some teams
get the workflow states of the first team
```

### to remove a label from a linear issue

Remove a label from a Linear issue.

**Input Concepts**

| Concept                  | Description                                       | Type           | Required | Default Value |
| ------------------------ | ------------------------------------------------- | -------------- | -------- | ------------- |
| [`issue`](#linear-issue) | The issue from which the label should be removed. | `linear issue` | Yes      | (no default)  |
| `label`                  | The exact label name to remove.                   | `text`         | Yes      | (no default)  |

**Output Concepts**

| Concept                   | Description                   | Type           |
| ------------------------- | ----------------------------- | -------------- |
| [`answer`](#linear-issue) | the issue: The updated issue. | `linear issue` |

**Examples**

```generic
get a linear issue by id
remove a label from the linear issue
   the label is "Bug"
```

### to search linear issues

Full-text search Linear issues.

**Input Concepts**

| Concept                | Description                              | Type          | Required | Default Value |
| ---------------------- | ---------------------------------------- | ------------- | -------- | ------------- |
| `search text`          | The text to search for in Linear issues. | `text`        | Yes      | (no default)  |
| [`team`](#linear-team) | Optional. Limit search to a Linear team. | `linear team` | No       | (no default)  |

**Output Concepts**

| Concept                   | Description                 | Type           |
| ------------------------- | --------------------------- | -------------- |
| [`answer`](#linear-issue) | the list of matching issues | `linear issue` |

**Examples**

```generic
search linear issues
   the search text is "authentication"
```

### to update a linear comment

Edit the text of an existing Linear comment.

**Input Concepts**

| Concept                      | Description                   | Type             | Required | Default Value |
| ---------------------------- | ----------------------------- | ---------------- | -------- | ------------- |
| [`comment`](#linear-comment) | The comment to edit.          | `linear comment` | Yes      | (no default)  |
| `body`                       | The new text for the comment. | `text`           | Yes      | (no default)  |

**Output Concepts**

| Concept                     | Description                       | Type             |
| --------------------------- | --------------------------------- | ---------------- |
| [`answer`](#linear-comment) | the comment: The updated comment. | `linear comment` |

**Examples**

```generic
get the comments on a linear issue
update the first linear comment
   the body is "Updated comment text."
```

### to update a linear project

Edit a Linear project's name or description.

**Input Concepts**

| Concept                      | Description                                | Type             | Required | Default Value |
| ---------------------------- | ------------------------------------------ | ---------------- | -------- | ------------- |
| [`project`](#linear-project) | The Linear project to update.              | `linear project` | Yes      | (no default)  |
| `name`                       | Optional. New name for the project.        | `text`           | No       | (no default)  |
| `description`                | Optional. New description for the project. | `text`           | No       | (no default)  |

**Output Concepts**

| Concept                     | Description                              | Type             |
| --------------------------- | ---------------------------------------- | ---------------- |
| [`answer`](#linear-project) | the project: The updated Linear project. | `linear project` |

**Examples**

```generic
get a linear project by name
update the linear project
   the name is "Q3 Launch Revised"
```

### to update an issue in linear

Update fields on an existing Linear issue.

**Input Concepts**

| Concept                    | Description                                                                                               | Type           | Required | Default Value |
| -------------------------- | --------------------------------------------------------------------------------------------------------- | -------------- | -------- | ------------- |
| [`issue`](#linear-issue)   | The issue to update.                                                                                      | `linear issue` | Yes      | (no default)  |
| `title`                    | Optional. New title for the issue.                                                                        | `text`         | No       | (no default)  |
| `description`              | Optional. New description for the issue.                                                                  | `text`         | No       | (no default)  |
| [`assignee`](#linear-user) | Optional. User to assign to the issue.                                                                    | `linear user`  | No       | (no default)  |
| `priority`                 | Optional. One of "No priority", "Urgent", "High", "Medium", or "Low".                                     | `text`         | No       | (no default)  |
| `status`                   | Optional. Workflow state name in the issue's team.                                                        | `text`         | No       | (no default)  |
| `labels`                   | Optional. Exact label names to set on the issue. Warning: this replaces all existing labels on the issue. | `text`         | No       | (no default)  |

**Output Concepts**

| Concept                   | Description                   | Type           |
| ------------------------- | ----------------------------- | -------------- |
| [`answer`](#linear-issue) | the issue: The updated issue. | `linear issue` |

**Examples**

```generic
get a linear issue by id
update the issue in linear
   the title is "Updated title"
```

## Concepts

### Linear issue

An issue in Linear

| Field Name                 | Description                                                             | Type                     |
| -------------------------- | ----------------------------------------------------------------------- | ------------------------ |
| `id`                       | The unique identifier for the issue.                                    | `text`                   |
| `number`                   | The number of the issue.                                                | `number`                 |
| `team`                     | The team the issue belongs to.                                          | `json`                   |
| `description`              | The description of the issue.                                           | `text`                   |
| `title`                    | The title of the issue.                                                 | `text`                   |
| `state`                    | The state of the issue.                                                 | `json`                   |
| `identifier`               | The workspace identifier for the issue, such as "INT-123".              | `optional[text]`         |
| `priority`                 | The numeric Linear priority.                                            | `optional[number]`       |
| `priority_label`           | The human-readable priority label.                                      | `optional[text]`         |
| `url`                      | The Linear web URL for the issue.                                       | `optional[text]`         |
| `team_name`                | The name of the team the issue belongs to (e.g. "Integrations").        | `optional[text]`         |
| `team_key`                 | The short key of the team the issue belongs to (e.g. "INT").            | `optional[text]`         |
| [`assignee`](#linear-user) | The user assigned to the issue, if any.                                 | `optional[linear user]`  |
| `labels`                   | The label names applied to the issue.                                   | `optional[list of text]` |
| `label_names`              | The label names joined into one string, for filtering (e.g. "Bug, P1"). | `optional[text]`         |
| `project_id`               | The ID of the project this issue belongs to, if any.                    | `optional[text]`         |
| `project_name`             | The name of the project this issue belongs to, if any.                  | `optional[text]`         |
| `cycle_id`                 | The ID of the cycle this issue is in, if any.                           | `optional[text]`         |
| `cycle_number`             | The number of the cycle this issue is in, if any.                       | `optional[number]`       |
| `created_at`               | The ISO timestamp when the issue was created.                           | `optional[text]`         |
| `updated_at`               | The ISO timestamp when the issue was last updated.                      | `optional[text]`         |

### Linear team

A team in Linear

| Field Name | Description                         | Type   |
| ---------- | ----------------------------------- | ------ |
| `id`       | The unique identifier for the team. | `text` |
| `name`     | The name of the team.               | `text` |
| `key`      | The short identifier for the team.  | `text` |

### Linear user

A user in Linear

| Field Name | Description                                  | Type      |
| ---------- | -------------------------------------------- | --------- |
| `id`       | The unique identifier for the user.          | `text`    |
| `email`    | The email address of the user.               | `text`    |
| `name`     | The name of the user.                        | `text`    |
| `is_me`    | Whether this user is the authenticated user. | `boolean` |

### Linear cycle

A cycle (sprint) in Linear

| Field Name    | Description                                         | Type             |
| ------------- | --------------------------------------------------- | ---------------- |
| `id`          | The unique identifier for the cycle.                | `text`           |
| `number`      | The sequential number of the cycle within its team. | `number`         |
| `name`        | The display name of the cycle, if set.              | `optional[text]` |
| `description` | An optional description of the cycle.               | `optional[text]` |
| `starts_at`   | The ISO timestamp when the cycle starts.            | `optional[text]` |
| `ends_at`     | The ISO timestamp when the cycle ends.              | `optional[text]` |

### Linear comment

A comment on a Linear issue

| Field Name   | Description                                          | Type             |
| ------------ | ---------------------------------------------------- | ---------------- |
| `id`         | The unique identifier for the comment.               | `text`           |
| `body`       | The text body of the comment.                        | `text`           |
| `url`        | The Linear web URL for the comment.                  | `optional[text]` |
| `created_at` | The ISO timestamp when the comment was created.      | `optional[text]` |
| `updated_at` | The ISO timestamp when the comment was last updated. | `optional[text]` |

### Linear project

A project in Linear

| Field Name    | Description                                                                   | Type             |
| ------------- | ----------------------------------------------------------------------------- | ---------------- |
| `id`          | The unique identifier for the project.                                        | `text`           |
| `name`        | The display name of the project.                                              | `text`           |
| `state`       | The current state of the project name (e.g. Backlog, In Progress, Completed). | `optional[text]` |
| `description` | An optional description of the project.                                       | `optional[text]` |
| `url`         | The Linear web URL for the project.                                           | `optional[text]` |
| `start_date`  | The project start date (YYYY-MM-DD), if set.                                  | `optional[text]` |
| `target_date` | The project target date (YYYY-MM-DD), if set.                                 | `optional[text]` |

### Linear notification

A notification for the authenticated Linear user

| Field Name   | Description                                               | Type             |
| ------------ | --------------------------------------------------------- | ---------------- |
| `id`         | The unique identifier for the notification.               | `text`           |
| `type`       | The notification type (e.g. issueAssignee, issueComment). | `text`           |
| `read_at`    | ISO timestamp when the notification was read, if read.    | `optional[text]` |
| `url`        | The Linear web URL related to the notification.           | `optional[text]` |
| `created_at` | The ISO timestamp when the notification was created.      | `optional[text]` |
| `updated_at` | The ISO timestamp when the notification was last updated. | `optional[text]` |

### Linear workflow state

A workflow state in Linear

| Field Name    | Description                                                        | Type             |
| ------------- | ------------------------------------------------------------------ | ---------------- |
| `id`          | The unique identifier for the state.                               | `text`           |
| `name`        | The display name of the state.                                     | `text`           |
| `state_type`  | The Linear type of the state (e.g. started, completed, cancelled). | `text`           |
| `description` | An optional description of the state.                              | `optional[text]` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/books/reference/linear.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.