Linear

Learn how to use Linear with Composio

Overview

SLUG: LINEAR

Description

Linear is a streamlined issue tracking and project planning tool for modern teams, featuring fast workflows, keyboard shortcuts, and GitHub integrations

Authentication Details

client_id
stringRequired
client_secret
stringRequired
oauth_redirect_uri
stringDefaults to https://backend.composio.dev/api/v1/auth-apps/add
scopes
stringDefaults to admin,read,write,issues:create,comments:create
generic_api_key
stringRequired

Connecting to Linear

Create an auth config

Use the dashboard to create an auth config for the Linear toolkit. This allows you to connect multiple Linear accounts to Composio for agents to use.

1

Select App

Navigate to Linear.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Linear Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using OAuth2

1from composio import Composio
2
3# Replace these with your actual values
4linear_auth_config_id = "ac_YOUR_LINEAR_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/application
6
7composio = Composio()
8
9
10def authenticate_toolkit(user_id: str, auth_config_id: str):
11 connection_request = composio.connected_accounts.initiate(
12 user_id=user_id,
13 auth_config_id=auth_config_id,
14 )
15
16 print(
17 f"Visit this URL to authenticate Linear: {connection_request.redirect_url}"
18 )
19
20 # This will wait for the auth flow to be completed
21 connection_request.wait_for_connection(timeout=15)
22 return connection_request.id
23
24
25connection_id = authenticate_toolkit(user_id, linear_auth_config_id)
26
27# You can also verify the connection status using:
28connected_account = composio.connected_accounts.get(connection_id)
29print(f"Connected account: {connected_account}")

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4linear_auth_config_id = "ac_YOUR_LINEAR_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10 # Replace this with a method to retrieve an API key from the user.
11 # Or supply your own.
12 user_api_key = input("[!] Enter API key")
13
14 connection_request = composio.connected_accounts.initiate(
15 user_id=user_id,
16 auth_config_id=auth_config_id,
17 config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18 )
19
20 # API Key authentication is immediate - no redirect needed
21 print(f"Successfully connected Linear for user {user_id}")
22 print(f"Connection status: {connection_request.status}")
23
24 return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, linear_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Linear toolkit’s playground

For code examples, see the Tool calling guide and Provider examples.

Tool List

Tool Name: Add reaction to comment

Description

Tool to add a reaction to an existing Linear comment. Use when you want to programmatically react to a comment on an issue.

Action Parameters

comment_id
stringRequired
emoji
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Create linear attachment

Description

Creates a new attachment and associates it with a specific, existing Linear issue.

Action Parameters

issue_id
stringRequired
subtitle
stringRequired
title
stringRequired
url
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Create a comment

Description

Creates a new comment on a specified Linear issue.

Action Parameters

body
stringRequired
issueId
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Create linear issue

Description

Creates a new issue in a specified Linear project and team, requiring team_id and title, and allowing for optional properties like description, assignee, state, priority, cycle, and due date.

Action Parameters

assignee_id
cycle_id
description
due_date
estimate
integer
label_ids
array
parent_id
priority
integer
project_id
state_id
team_id
stringRequired
title
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get create issue default params

Description

Fetches a Linear team's default issue estimate and state, useful for pre-filling new issue forms.

Action Parameters

team_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Create a label

Description

Creates a new label in Linear for a specified team, used to categorize and organize issues. Label names must be unique within each team. If a label with the same name already exists, the existing label will be returned.

Action Parameters

color
stringRequired
description
name
stringRequired
team_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Create Project

Description

Creates a new Linear project with specified name and team associations.

Action Parameters

color
description
icon
lead_id
name
stringRequired
priority
start_date
target_date
team_ids
arrayRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Delete issue

Description

Archives an existing Linear issue by its ID, which is Linear's standard way of deleting issues; the operation is idempotent.

Action Parameters

issue_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get all teams

Description

Retrieves all teams from the Linear workspace without requiring any parameters.

Action Parameters

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Download issue attachments

Description

Downloads a specific attachment from a Linear issue; the `file_name` must include the correct file extension.

Action Parameters

attachment_id
stringRequired
file_name
stringRequired
issue_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get current user

Description

Gets the currently authenticated user's ID, name, email, and other profile information. Use this to identify 'me' in other Linear operations that require user ID filtering.

Action Parameters

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get cycles by team ID

Description

Retrieves all cycles for a specified Linear team ID; cycles are time-boxed work periods (like sprints) and the team ID must correspond to an existing team.

Action Parameters

team_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get Linear issue

Description

Retrieves an existing Linear issue's comprehensive details, including id, identifier, title, description, timestamps, state, team, creator, attachments, comments, and due date.

Action Parameters

issue_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get Linear project

Description

Retrieves a single Linear project by its unique identifier. Use when verifying a newly created or updated project, or when fetching detailed project information by ID.

Action Parameters

include_initiatives
boolean
include_members
boolean
include_teams
boolean
project_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: List issue drafts

Description

Tool to list issue drafts. Use when you need to fetch draft issues for review or further editing.

Action Parameters

after
first
integerDefaults to 50

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: List issues by team ID

Description

Tool to list all issues for a specific Linear team, scoped by team ID. Use when you need to retrieve issues belonging to a particular team without fetching workspace-wide issues. This is more efficient than workspace-wide listing followed by client-side filtering.

Action Parameters

after
first
integerDefaults to 50
include_archived
boolean
team_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get all cycles

Description

Retrieves all cycles (time-boxed iterations for work) from the Linear account; no filters are applied.

Action Parameters

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: List Linear issues

Description

Lists non-archived Linear issues; if project_id is not specified, issues from all accessible projects are returned. Can also filter by assignee_id to get issues assigned to a specific user.

Action Parameters

after
assignee_id
first
integerDefaults to 10
project_id

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get labels

Description

Retrieves labels from Linear. If team_id is provided, returns labels for that specific team. If team_id is omitted, returns all labels across the workspace.

Action Parameters

team_id

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: List linear projects

Description

Retrieves all projects from the Linear account.

Action Parameters

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: List Linear states

Description

Retrieves all workflow states for a specified team in Linear, representing the stages an issue progresses through in that team's workflow.

Action Parameters

team_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Get teams

Description

Retrieves all teams with their members. Optionally filters each team's associated projects by project_id.

Action Parameters

project_id

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: List Linear users

Description

Lists all users in the Linear workspace with their IDs, names, emails, and active status.

Action Parameters

after
first
integerDefaults to 50

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Manage draft

Description

Tool to create, update, or delete issue drafts in Linear. Use when you need to save or modify draft notes before converting to an issue. Note: Linear's public GraphQL API does not expose explicit Issue Draft mutations. This action leverages standard Issue mutations to emulate draft management: - create -> issueCreate - update -> issueUpdate - delete -> issueDelete The response maps the created/updated Issue fields to the DraftModel for compatibility.

Action Parameters

description
id
operation
stringRequired
team_id
title

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Remove label from Linear issue

Description

Removes a specified label from an existing Linear issue using their IDs; successful even if the label isn't on the issue.

Action Parameters

issue_id
stringRequired
label_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Remove reaction from comment

Description

Tool to remove a reaction on a comment. Use when you have a reaction ID and need to delete it.

Action Parameters

reaction_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Run Query or Mutation

Description

Execute any GraphQL query or mutation against Linear's API. USE WHEN: No dedicated action exists, need complex filtering, custom fields, or schema discovery. *** INTROSPECTION FIRST - NEVER GUESS FIELD NAMES *** Run introspection before unknown operations: - query { __type(name: "Issue") { fields { name } } } - query { __type(name: "Mutation") { fields { name } } } Linear uses nested objects (project { id }), NOT scalar IDs (projectId). KEY: All IDs are UUIDs. Filter: { field: { eq: value } }. Pagination: nodes[] + pageInfo.

Action Parameters

query_or_mutation
stringRequired
variables
object

Action Response

data
error
errors
extensions
successful
booleanRequired

Tool Name: Update issue

Description

Updates an existing Linear issue using its `issue_id`; requires at least one other attribute for modification, and all provided entity IDs (for state, assignee, labels, etc.) must be valid.

Action Parameters

assigneeId
description
dueDate
estimate
issueId
stringRequired
labelIds
parentId
priority
projectId
stateId
teamId
title

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Update a comment

Description

Tool to update an existing Linear comment's body text. Use when you need to edit or modify the content of a previously created comment.

Action Parameters

body
stringRequired
comment_id
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired

Tool Name: Update Project

Description

Tool to update an existing Linear project. Use when you need to modify project properties like name, description, state, dates, or lead. All fields except project_id are optional - only provide the fields you want to update.

Action Parameters

color
description
icon
lead_id
name
priority
project_id
stringRequired
start_date
state
status_id
target_date

Action Response

data
objectRequired
error
successful
booleanRequired