> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Connect your bot to Linear using the official integration.

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01KRHWEFJX783DXZG4XZ7B6ER8)
*v2.5.0*

The official Linear integration lets your bot automate issue workflows and react to repository file events.

## Setup

> [tab] Basic configuration
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Linear](https://linear.app) account with access to the workspace you want to connect
>
> **Step 1**
>
> In Botpress Studio, select **Explore Hub** in the upper-right corner.
>
> **Step 2**
>
> Search for the **Linear** integration, then select **Install Integration**.
>
> **Step 3**
>
> In the **Configuration** menu, select **Authorize Linear**.
>
> **Step 4**
>
> Follow the on-screen instructions to connect Botpress to your Linear workspace.
>
> > [!NOTE]
> >
> > When using this configuration mode, Botpress connects to Linear using OAuth. Actions taken by the bot use the Linear account that completed authorization.
> >
> > If you need an API key, webhook signing secret, or more control over how Linear sends events to Botpress, use [Manual configuration](#manual-configuration) instead.

> [tab] Manual configuration
>
> For advanced use cases, you can configure the integration with a Linear **API key** and **Webhook Signing Secret** instead of OAuth.
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Linear](https://linear.app) account with access to the workspace you want to connect
>
> ### Creating a Linear API key
>
> **Step 1**
>
> On Linear, navigate to your account settings and select the **API** tab in the navigation sidebar.
>
> **Step 2**
>
> Under **Personal API keys**, enter a name for your API key and select **Create new API key**.
>
> **Step 3**
>
> Save this API key in a secure location. You will need it to configure the Linear integration in Botpress.
>
> > [!NOTE]
> >
> > Treat API keys like passwords. Store them securely and rotate them if they’re exposed.
>
> ### Subscribing to Linear webhook events
>
> **Step 1**
>
> In Botpress, open the **Configuration** page for the Linear integration.
>
> **Step 2**
>
> Copy the **Webhook URL** generated by Botpress.
>
> **Step 3**
>
> On Linear, go to your account settings and select the **API** tab in the navigation sidebar.
>
> **Step 4**
>
> Under **Webhooks**, select **Create new webhook**.
>
> **Step 5**
>
> Enter a name for the webhook and paste the webhook URL from Botpress into the **URL** field.
>
> **Step 6**
>
> Copy the **webhook signing secret** and store it in a secure location. You will need it to configure the Linear integration in Botpress.
>
> **Step 7**
>
> Under **Data change events**, choose the events to subscribe to:
>
> * **Issues**: Receive notifications when issues are created, updated, or deleted.
> * **Comments**: Receive notifications when comments are added to issues.
>
> **Step 8**
>
> Under **Teams**, select the teams you want to receive notifications for.
>
> **Step 9**
>
> Select **Create webhook** to save your changes.
>
> ### Configuring the Linear integration in Botpress
>
> **Step 1**
>
> In Botpress, open the **Configuration** page for the Linear integration.
>
> **Step 2**
>
> Select **Configure Linear with an API Key**.
>
> **Step 3**
>
> Enter the API key from Linear in the **API Key** field.
>
> **Step 4**
>
> Enter the webhook signing secret from Linear in the **Webhook Signing Secret** field.
>
> **Step 5**
>
> Save the configuration and enable the integration.
>
> > [!TIP]
> >
> > Your Linear integration is ready. Use the **Cards** and **Triggers** sections below to build your workflows.

***

## Cards

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### Create Issue

Create an issue on Linear

**input** `object`

**title** `string` *required*

The issue's title

**description** `string` *required*

The content of the issue

**priority** `number`

0 = none, 1 = urgent, 2 = high, 3 = medium, 4 = low

**teamName** `string` *required*

Name of the team to assign the issue to

**labels** `array`

One or multiple labels to assign to this issue

**project** `string`

A project to associate to this issue

**output** `object`

**issue** `object` *required*

The created issue

**title** `string` *required*

The issue title on Linear, such as "Fix the bug

**number** `number` *required*

The issue number on Linear, such as "123" in XXX-123

**createdAt** `string (date-time)` *required*

The ISO date the issue was created

**updatedAt** `string (date-time)` *required*

The ISO date the issue was last updated

**identifier** `string` *required*

Issue's human readable identifier (e.g. XXX-123)

**url** `string` *required*

The URL of the issue on Linear

**priority** `number` *required*

Priority of the issue, such as "1" for "Urgent", 0 for "No Priority"

**description** `string`

A markdown description of the issue. Images and videos are inlined using markdown links.

**id** `string` *required*

The issue ID on Linear

**estimate** `number`

The estimate of the issue in points

### Delete Issue

Delete an issue on Linear

**input** `object`

**id** `string` *required*

The issue ID on Linear. Ex: \{\{event.payload.linearIds.issueId}}

**output** `object`

This Card has no output.

### Find Target

Find a target on Linear

**input** `object`

**query** `string` *required*

Issue title, description, or number

**channel** `enum\<string\>` *required*

The channel to search in

Available options: `issue`

**output** `object`

**targets** `array` *required*

The list of issues found

**array item properties**

**displayName** `string` *required*

The name of the issue

**tags** `object` *required*

The tags applied to the issue

**channel** `enum\<string\>` *required*

The channel of the search result

Available options: `issue`

### Get Issue

Get an issue by its ID

**input** `object`

**issueId** `string` *required*

The issue ID on Linear. Ex: \{\{event.payload.linearIds.issueId}}

**output** `object`

The issue found

**title** `string` *required*

The issue title on Linear, such as "Fix the bug

**number** `number` *required*

The issue number on Linear, such as "123" in XXX-123

**createdAt** `string (date-time)` *required*

The ISO date the issue was created

**updatedAt** `string (date-time)` *required*

The ISO date the issue was last updated

**identifier** `string` *required*

Issue's human readable identifier (e.g. XXX-123)

**url** `string` *required*

The URL of the issue on Linear

**priority** `number` *required*

Priority of the issue, such as "1" for "Urgent", 0 for "No Priority"

**description** `string`

A markdown description of the issue. Images and videos are inlined using markdown links.

**id** `string` *required*

The issue ID on Linear

**estimate** `number`

The estimate of the issue in points

### Get or Create a Conversation

Proactively create a conversation from a bot

**input** `object`

**conversation** `object` *required*

**id** `string` *required*

The issue ID on Linear

**output** `object`

**conversationId** `string` *required*

The Botpress ID of the created conversation

### Get User Profile

Get a user profile from Linear

**input** `object`

**linearUserId** `string`

The user's ID on Linear. Ex: \{\{event.payload.linearIds.creatorId}}. If omitted, returns the current user.

**output** `object`

The user profile

**linearId** `string` *required*

Linear User ID

**admin** `boolean` *required*

Indicates if the user is an admin of the organization

**archivedAt** `string (date-time)`

Date when the user was archived

**avatarUrl** `string (uri)`

The URL for the profile picture

**createdAt** `string (date-time)` *required*

Date when the user was created

**description** `string`

A short description of the user, either its title or bio

**displayName** `string` *required*

The user's display (nick) name. Unique within each organization

**guest** `boolean` *required*

Whether the user is a guest in the workspace and limited to accessing a subset of teams

**email** `string` *required*

The user's email address

**isMe** `boolean` *required*

Whether the user is the currently authenticated user

**url** `string` *required*

User's profile URL

**timezone** `string`

The local timezone of the user

**name** `string` *required*

The user's full name

### Issue Delete

**input** `object`

**id** `string` *required*

The unique identifier for the deletable item

**output** `object`

This Card has no output.

### Issue List

**input** `object`

**nextToken** `string`

The token to get a given list of items (e.g. a parent record ID, or a page index).

**output** `object`

**items** `array` *required*

**meta** `object` *required*

Metadata for the list operation

**nextToken** `string`

The token to get a given list of items (e.g. a parent record ID, or a page index).

### List Issues

List issues from Linear

**input** `object`

**count** `number` (default: 10)

The number of issues to return

**startCursor** `string`

The cursor to start from

**teamId** `string`

The team ID to filter by

**startDate** `string`

Ignore issues created before this date

**output** `object`

**issues** `array` *required*

The list of matching issues

**array item properties**

**title** `string` *required*

The issue title on Linear, such as "Fix the bug

**number** `number` *required*

The issue number on Linear, such as "123" in XXX-123

**createdAt** `string (date-time)` *required*

The ISO date the issue was created

**updatedAt** `string (date-time)` *required*

The ISO date the issue was last updated

**identifier** `string` *required*

Issue's human readable identifier (e.g. XXX-123)

**url** `string` *required*

The URL of the issue on Linear

**priority** `number` *required*

Priority of the issue, such as "1" for "Urgent", 0 for "No Priority"

**description** `string`

A markdown description of the issue. Images and videos are inlined using markdown links.

**id** `string` *required*

The issue ID on Linear

**estimate** `number`

The estimate of the issue in points

**linearIds** `object` *required*

The Linear IDs of the referenced entities

**creatorId** `string`

The internal Linear User ID of the user who created the issue

**labelIds** `array`

The internal Linear Label IDs associated with the issue

**issueId** `string` *required*

The internal Linear Issue ID

**teamId** `string`

The internal Linear Team ID

**projectId** `string`

The internal Linear Project ID

**assigneeId** `string`

The internal Linear Assignee ID

**subscriberIds** `array`

The internal Linear Subscriber User IDs

**nextCursor** `string`

The cursor to fetch the next page

### List States

List states from Linear

**input** `object`

**count** `number` (default: 10)

The number of states to return

**startCursor** `string`

The cursor to start from

**output** `object`

**states** `array` *required*

The list of states

**array item properties**

**id** `string` *required*

The unique identifier of the entity

**name** `string` *required*

The state's name

**nextCursor** `string`

The cursor to fetch the next page

### List Teams

List teams from Linear

**input** `object`

This Card has no input fields.

**output** `object`

**teams** `array` *required*

The list of teams

**array item properties**

**id** `string` *required*

The unique identifier of the entity

**key** `string` *required*

The team's key

**name** `string` *required*

The team's name

**description** `string`

The team's description

**icon** `string`

The icon of the team

### List Users

List users from Linear

**input** `object`

**count** `number` (default: 10)

The number of users to return

**startCursor** `string`

The cursor to start from

**output** `object`

**users** `array` *required*

The list of matching users

**array item properties**

**id** `string` *required*

The user ID on Linear

**email** `string` *required*

The user's email address

**name** `string` *required*

The user's nickname

**displayName** `string` *required*

The user's display name

**avatarUrl** `string`

The URL of the user avatar

**description** `string`

The user's description, such as their title or bio

**lastSeen** `string`

The last time the user was seen

**updatedAt** `string (date-time)` *required*

The last time the user was updated

**nextCursor** `string`

The cursor to fetch the next page

### Mark Issue as Duplicate

Mark an issue as a duplicate of another

**input** `object`

**issueId** `string` *required*

The issue ID on Linear. Ex: \{\{event.payload.linearIds.issueId}}

**relatedIssueId** `string` *required*

The ID of the existing issue on Linear

**output** `object`

This Card has no output.

### Resolve Comment

Resolve a comment by id

**input** `object`

**id** `string` *required*

The comment ID

**output** `object`

**success** `boolean` *required*

Whether the operation was successful

### Send Raw GraphQL Query

Send a raw GraphQL query to the linear API

**input** `object`

**query** `string` *required*

The GraphQL query

**parameters** `array`

The query parameters

**array item properties**

**name** `string` *required*

The parameter name

**value** `string`

The parameter value

**output** `object`

**result** `string`

The query result

### Update Issue

Update an issue on Linear

**input** `object`

**issueId** `string` *required*

The issue ID on Linear. Example: \{\{event.payload.id}}

**priority** `number`

0 = none, 1 = urgent, 2 = high, 3 = medium, 4 = low

**teamName** `string`

Type a name to change the assigned team of the issue

**labels** `array`

One or multiple labels to assign to this issue

**project** `string`

A project to associate to this issue

**output** `object`

**issue** `object`

The updated issue

**title** `string` *required*

The issue title on Linear, such as "Fix the bug

**number** `number` *required*

The issue number on Linear, such as "123" in XXX-123

**createdAt** `string (date-time)` *required*

The ISO date the issue was created

**updatedAt** `string (date-time)` *required*

The ISO date the issue was last updated

**identifier** `string` *required*

Issue's human readable identifier (e.g. XXX-123)

**url** `string` *required*

The URL of the issue on Linear

**priority** `number` *required*

Priority of the issue, such as "1" for "Urgent", 0 for "No Priority"

**description** `string`

A markdown description of the issue. Images and videos are inlined using markdown links.

**id** `string` *required*

The issue ID on Linear

**estimate** `number`

The estimate of the issue in points

***

## Triggers

{/* vale off */}

Here's a reference for all [Triggers](https://botpress.com/docs/studio/concepts/triggers.md) available with the integration:

> [!TIP]
>
> You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.

### Aggregate File Changes

**payload** `object`

**modifiedItems** `object` *required*

The modified items

**created** `array` *required*

The files created

**array item properties**

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

**updated** `array` *required*

The files updated

**array item properties**

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

**deleted** `array` *required*

The files and folders deleted

> [tab] file
>
> **id** `string` *required*
>
> The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.
>
> **type** `string` *required*
>
> **name** `string` *required*
>
> The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."
>
> **parentId** `string`
>
> The parent folder ID. Leave empty if the file is in the root folder.
>
> **absolutePath** `string` *required*
>
> The full path of the file
>
> **sizeInBytes** `number`
>
> The file size in bytes, if available
>
> **lastModifiedDate** `string (date-time)`
>
> The last modified date of the file, if available
>
> **contentHash** `string`
>
> The hash of the file content, or version/revision number, if available

> [tab] folder
>
> **id** `string` *required*
>
> The folder's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.
>
> **type** `string` *required*
>
> **name** `string` *required*
>
> The folder's name. This will be displayed in the Botpress UI and be used as the folder's name on Files API."
>
> **parentId** `string`
>
> The parent folder ID. Leave empty if the folder is in the root folder.
>
> **absolutePath** `string` *required*
>
> The full path of the folder

### File Created

**payload** `object`

**file** `object` *required*

The created file

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

### File Deleted

**payload** `object`

**file** `object` *required*

The deleted file

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

### File Updated

**payload** `object`

**file** `object` *required*

The updated file

**id** `string` *required*

The file's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The file's name. This will be displayed in the Botpress UI and be used as the file's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the file is in the root folder.

**absolutePath** `string` *required*

The full path of the file

**sizeInBytes** `number`

The file size in bytes, if available

**lastModifiedDate** `string (date-time)`

The last modified date of the file, if available

**contentHash** `string`

The hash of the file content, or version/revision number, if available

### Folder Deleted Recursive

**payload** `object`

**folder** `object` *required*

The deleted folder

**id** `string` *required*

The folder's ID. This could be a unique identifier from the external service, or a relative or absolute path, so long as it's unique.

**type** `string` *required*

**name** `string` *required*

The folder's name. This will be displayed in the Botpress UI and be used as the folder's name on Files API."

**parentId** `string`

The parent folder ID. Leave empty if the folder is in the root folder.

**absolutePath** `string` *required*

The full path of the folder

### Issue Created

Triggered when an issue is created

**payload** `object`

**title** `string` *required*

The issue title on Linear, such as "Fix the bug

**number** `number` *required*

The issue number on Linear, such as "123" in XXX-123

**createdAt** `string (date-time)` *required*

The ISO date the issue was created

**updatedAt** `string (date-time)` *required*

The ISO date the issue was last updated

**identifier** `string` *required*

Issue's human readable identifier (e.g. XXX-123)

**url** `string` *required*

The URL of the issue on Linear

**priority** `number` *required*

Priority of the issue, such as "1" for "Urgent", 0 for "No Priority"

**description** `string`

A markdown description of the issue. Images and videos are inlined using markdown links.

**teamName** `string`

The name of the Linear team the issue currently belongs to, such as "Customer Support"

**teamKey** `string`

The key of the Linear team the issue currently belongs to, such as "XXX" in XXX-123

**status** `string` *required*

The issue State name (such as "In Progress"

**statusColor** `string` *required*

The issue State color (#000000 format)

**statusType** `string` *required*

The issue State type

**labels** `array`

Label names

**linearIds** `object` *required*

The Linear IDs of the referenced entities

**creatorId** `string`

The internal Linear User ID of the user who created the issue

**labelIds** `array`

The internal Linear Label IDs associated with the issue

**issueId** `string` *required*

The internal Linear Issue ID

**teamId** `string`

The internal Linear Team ID

**projectId** `string`

The internal Linear Project ID

**assigneeId** `string`

The internal Linear Assignee ID

**subscriberIds** `array`

The internal Linear Subscriber User IDs

**userId** `string`

The Botpress User ID of the individual who initiated the issue. If not provided, it indicates the issue was generated by the bot.

**conversationId** `string` *required*

Botpress Conversation ID of the issue

**targets** `object` *required*

The issue that was created

**issue** `object`

The target issue on Linear

### Issue Deleted

Triggered when an issue is deleted

**payload** `object`

**title** `string` *required*

The issue title on Linear, such as "Fix the bug

**number** `number` *required*

The issue number on Linear, such as "123" in XXX-123

**createdAt** `string (date-time)` *required*

The ISO date the issue was created

**updatedAt** `string (date-time)` *required*

The ISO date the issue was last updated

**identifier** `string` *required*

Issue's human readable identifier (e.g. XXX-123)

**url** `string` *required*

The URL of the issue on Linear

**priority** `number` *required*

Priority of the issue, such as "1" for "Urgent", 0 for "No Priority"

**description** `string`

A markdown description of the issue. Images and videos are inlined using markdown links.

**teamName** `string`

The name of the Linear team the issue currently belongs to, such as "Customer Support"

**teamKey** `string`

The key of the Linear team the issue currently belongs to, such as "XXX" in XXX-123

**status** `string` *required*

The issue State name (such as "In Progress"

**statusColor** `string` *required*

The issue State color (#000000 format)

**statusType** `string` *required*

The issue State type

**labels** `array`

Label names

**linearIds** `object` *required*

The Linear IDs of the referenced entities

**creatorId** `string`

The internal Linear User ID of the user who created the issue

**labelIds** `array`

The internal Linear Label IDs associated with the issue

**issueId** `string` *required*

The internal Linear Issue ID

**teamId** `string`

The internal Linear Team ID

**projectId** `string`

The internal Linear Project ID

**assigneeId** `string`

The internal Linear Assignee ID

**subscriberIds** `array`

The internal Linear Subscriber User IDs

**id** `string` *required*

The unique identifier for the deletable item

### Issue Updated

Triggered when an issue is updated

**payload** `object`

**title** `string` *required*

The issue title on Linear, such as "Fix the bug

**number** `number` *required*

The issue number on Linear, such as "123" in XXX-123

**createdAt** `string (date-time)` *required*

The ISO date the issue was created

**updatedAt** `string (date-time)` *required*

The ISO date the issue was last updated

**identifier** `string` *required*

Issue's human readable identifier (e.g. XXX-123)

**url** `string` *required*

The URL of the issue on Linear

**priority** `number` *required*

Priority of the issue, such as "1" for "Urgent", 0 for "No Priority"

**description** `string`

A markdown description of the issue. Images and videos are inlined using markdown links.

**teamName** `string`

The name of the Linear team the issue currently belongs to, such as "Customer Support"

**teamKey** `string`

The key of the Linear team the issue currently belongs to, such as "XXX" in XXX-123

**status** `string` *required*

The issue State name (such as "In Progress"

**statusColor** `string` *required*

The issue State color (#000000 format)

**statusType** `string` *required*

The issue State type

**labels** `array`

Label names

**linearIds** `object` *required*

The Linear IDs of the referenced entities

**creatorId** `string`

The internal Linear User ID of the user who created the issue

**labelIds** `array`

The internal Linear Label IDs associated with the issue

**issueId** `string` *required*

The internal Linear Issue ID

**teamId** `string`

The internal Linear Team ID

**projectId** `string`

The internal Linear Project ID

**assigneeId** `string`

The internal Linear Assignee ID

**subscriberIds** `array`

The internal Linear Subscriber User IDs

**userId** `string`

The Botpress User ID of the individual who initiated the issue. If not provided, it indicates the issue was generated by the bot.

**conversationId** `string` *required*

Botpress Conversation ID of the issue

**targets** `object` *required*

The issue that was updated

**issue** `object`

The target issue on Linear


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.