Linear

Procedures and concepts for the Linear integration.

The following documentation is for Linear v1.4.0 (BDK).

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 Install or Add Connection to add the book to your agent.

4. If adding a connection, you'll be prompted for 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	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	the issue: The updated issue.	linear issue

Examples

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	The Linear issue to add.	linear issue	Yes	(no default)
cycle	The Linear cycle to add the issue to.	linear cycle	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	the issue: The updated issue.	linear issue

Examples

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	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	the comment: The created comment.	linear comment

Examples

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	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	the project: The created Linear project.	linear project

Examples

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	The team in which you want to create the issue.	linear team	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	the issue: The created issue.	linear issue

Examples

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	The comment to delete.	linear comment	Yes	(no default)

Output Concepts

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

Examples

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	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

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	The issue to subscribe to.	linear issue	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	Whether the subscription was successful.	boolean

Examples

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	the issue: The matching Linear issue.	linear issue

Examples

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	the user: The matching Linear user.	linear user

Examples

get a linear user
   the user query is "[e-mail]"

to get all linear users

List all users in the Linear workspace.

Output Concepts

Concept	Description	Type
answer	the list of workspace users	linear user

Examples

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	The Linear issue whose comments should be returned.	linear issue	Yes	(no default)

Output Concepts

Concept	Description	Type
comments	the list of comments on the issue	linear comment

Examples

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	The Linear team whose cycles should be returned.	linear team	Yes	(no default)

Output Concepts

Concept	Description	Type
cycles	the list of cycles for the team	linear cycle

Examples

get some teams
get the cycles of the first team

to get the (issues)

FILTER - CAPABLE

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	the list of issues	linear issue

Examples

the states are "Todo", "Backlog" and "In Progress"
get the issues whose assignee email is "[e-mail]" and whose state name is in the states

get the issues whose title contains "authentication"

get the issues whose state name is "In Progress"

get the labels
get the issues with label "ComplexityLow"

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

get the labels

to get the (notifications) from linear

Fetch notifications for the authenticated Linear user.

Output Concepts

Concept	Description	Type
notifications	the list of notifications	linear notification

Examples

get the notifications from linear

to get the (projects) from linear

FILTER - CAPABLE

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

Output Concepts

Concept	Description	Type
projects	the list of Linear projects	linear project

Examples

get the projects from linear

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

to get the (teams)

FILTER - CAPABLE

Fetch the teams matching the filters (if any).

Output Concepts

Concept	Description	Type
teams	the list of teams	linear team

Examples

get some teams

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	The linear team from which you want to get the users.	linear team	Yes	(no default)

Output Concepts

Concept	Description	Type
users	the users: The list of users in the team.	linear user

Examples

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	The Linear team whose workflow states should be returned.	linear team	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	the list of workflow states	linear workflow state

Examples

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	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	the issue: The updated issue.	linear issue

Examples

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	Optional. Limit search to a Linear team.	linear team	No	(no default)

Output Concepts

Concept	Description	Type
answer	the list of matching issues	linear issue

Examples

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	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	the comment: The updated comment.	linear comment

Examples

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	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	the project: The updated Linear project.	linear project

Examples

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	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	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	the issue: The updated issue.	linear issue

Examples

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	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]