Linear connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your Linear credentials with Scalekit so it handles the token lifecycle. You do this once per environment.

   Dashboard setup steps

   Register your Scalekit environment with the Linear connector so Scalekit handles the authentication flow and token lifecycle for you. The connection name you create will be used to identify and invoke the connection programmatically. Then complete the configuration in your application as follows:

   1. Set up auth redirects

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Linear and click Create. Copy the redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

        

      • Log in to Linear and go to Settings → API → OAuth applications.

      • Click New application, enter an application name and description, then paste the redirect URI from Scalekit into the Callback URLs field. Click Create application.

        

   2. Get client credentials

      • In your Linear OAuth application, copy the Client ID and Client Secret.

   3. Add credentials in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections and open the connection you created.

      • Enter your credentials:

        • Client ID (from above)
        • Client Secret (from above)
        • Permissions (scopes — see Linear OAuth scopes reference)

        

      • Click Save.

4. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'linear'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Linear:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'linear_issues_list',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "linear"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Linear:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="linear_issues_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Read issues — fetch issues, projects, cycles, and team details
• Create and update issues — file new issues, update status, set priority, and assign teammates
• Manage projects — create and update project metadata and milestones
• Search — find issues by keyword, assignee, label, or state

Common workflows

Proxy API call

Node.js

// Make a GraphQL request via Scalekit proxy
const result = await actions.request({
  connectionName: 'linear',
  identifier: 'user_123',
  path: '/graphql',
  method: 'POST',
  body: JSON.stringify({ query: '{ viewer { id name email } }' }),
});
console.log(result);

Python

import json

# Make a GraphQL request via Scalekit proxy
result = actions.request(
    connection_name='linear',
    identifier='user_123',
    path="/graphql",
    method="POST",
    body=json.dumps({"query": "{ viewer { id name email } }"})
)
print(result)

Execute a tool

Node.js

const result = await actions.executeTool({
  connector: 'linear',
  identifier: 'user_123',
  toolName: 'linear_graphql_query',
  toolInput: {
    query: '{ viewer { id name email } }',
  },
});
console.log(result);

Python

result = actions.execute_tool(
    connection_name='linear',
    identifier='user_123',
    tool_name='linear_graphql_query',
    tool_input={
        "query": "{ viewer { id name email } }",
    },
)
print(result)

Getting resource IDs

Most Linear tools require one or more IDs. Always fetch IDs from the API — never guess or hard-code them.

Resource	Tool to get ID	Field in response
Team ID	linear_teams_list	teams.nodes[].id
Issue ID	linear_issues_list or linear_issue_search	issues.nodes[].id
Project ID	linear_projects_list	projects.nodes[].id
Cycle ID	linear_cycles_list	cycles.nodes[].id
Label ID	linear_labels_list	issueLabels.nodes[].id
Workflow State ID	linear_workflow_states_list	workflowStates.nodes[].id
User ID	linear_users_list	users.nodes[].id
Comment ID	linear_comments_list	comments.nodes[].id
Attachment ID	linear_issue_get (include attachments)	issue.attachments.nodes[].id
Webhook ID	linear_webhooks_list	webhooks.nodes[].id
Milestone ID	linear_project_milestones_list	projectMilestones.nodes[].id
Roadmap ID	linear_roadmaps_list	roadmaps.nodes[].id

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

linear_attachment_create#Create an external link attachment on a Linear issue.4 params▾

Create an external link attachment on a Linear issue.

NameTypeRequiredDescription

issueIdstringrequiredID of the issue to attach the link to

titlestringrequiredAttachment title

urlstringrequiredURL of the attachment

subtitlestringoptionalSubtitle or description for the attachment

linear_attachment_delete#Delete an attachment from a Linear issue.1 param▾

Delete an attachment from a Linear issue.

NameTypeRequiredDescription

attachmentIdstringrequiredID of the attachment to delete

linear_attachment_update#Update the title or subtitle of an existing attachment on a Linear issue.3 params▾

Update the title or subtitle of an existing attachment on a Linear issue.

NameTypeRequiredDescription

attachmentIdstringrequiredID of the attachment to update

titlestringrequiredNew title for the attachment

subtitlestringoptionalNew subtitle or description

linear_comment_create#Create a comment on a Linear issue.2 params▾

Create a comment on a Linear issue.

NameTypeRequiredDescription

bodystringrequiredComment text

issueIdstringrequiredID of the issue to comment on

linear_comment_delete#Permanently delete a comment from a Linear issue.1 param▾

Permanently delete a comment from a Linear issue.

NameTypeRequiredDescription

commentIdstringrequiredID of the comment to delete

linear_comment_get#Retrieve a single comment by its ID.1 param▾

Retrieve a single comment by its ID.

NameTypeRequiredDescription

commentIdstringrequiredID of the comment to retrieve

linear_comment_update#Update the text body of an existing Linear comment.2 params▾

Update the text body of an existing Linear comment.

NameTypeRequiredDescription

bodystringrequiredUpdated comment text

commentIdstringrequiredID of the comment to update

linear_comments_list#List all comments on a specific Linear issue with pagination support.3 params▾

List all comments on a specific Linear issue with pagination support.

NameTypeRequiredDescription

issueIdstringrequiredID of the issue to list comments for

afterstringoptionalPagination cursor for fetching the next page

firstintegeroptionalNumber of comments to return

linear_cycle_create#Create a new cycle (sprint) for a Linear team. Requires a team ID, start date, and end date.5 params▾

Create a new cycle (sprint) for a Linear team. Requires a team ID, start date, and end date.

NameTypeRequiredDescription

endsAtstringrequiredCycle end date-time in ISO 8601 format

startsAtstringrequiredCycle start date-time in ISO 8601 format

teamIdstringrequiredID of the team to create the cycle in

descriptionstringoptionalOptional description of the cycle

namestringoptionalOptional custom name for the cycle

linear_cycle_get#Get a specific Linear cycle by ID, including its issues.1 param▾

Get a specific Linear cycle by ID, including its issues.

NameTypeRequiredDescription

cycleIdstringrequiredID of the cycle to retrieve

linear_cycle_issues_list#List all issues in a specific Linear cycle with pagination support.3 params▾

List all issues in a specific Linear cycle with pagination support.

NameTypeRequiredDescription

cycleIdstringrequiredID of the cycle to list issues for

afterstringoptionalPagination cursor for fetching the next page

firstintegeroptionalNumber of issues to return

linear_cycle_update#Update an existing cycle (sprint) in Linear.5 params▾

Update an existing cycle (sprint) in Linear.

NameTypeRequiredDescription

cycleIdstringrequiredID of the cycle to update

descriptionstringoptionalNew description for the cycle

endsAtstringoptionalNew end date-time in ISO 8601 format

namestringoptionalNew name for the cycle

startsAtstringoptionalNew start date-time in ISO 8601 format

linear_cycles_list#List cycles (sprints) for a Linear team with pagination support.3 params▾

List cycles (sprints) for a Linear team with pagination support.

NameTypeRequiredDescription

teamIdstringrequiredTeam ID to list cycles for

afterstringoptionalPagination cursor for fetching the next page

firstintegeroptionalNumber of cycles to return

linear_graphql_query#Execute a custom GraphQL query or mutation against the Linear API. Allows running any valid GraphQL operation with variables support for advanced use cases.2 params▾

Execute a custom GraphQL query or mutation against the Linear API. Allows running any valid GraphQL operation with variables support for advanced use cases.

NameTypeRequiredDescription

querystringrequiredThe GraphQL query or mutation to execute

variablesobjectoptionalVariables to pass to the GraphQL query

linear_issue_archive#Archive a Linear issue by ID using the issueArchive mutation.1 param▾

Archive a Linear issue by ID using the issueArchive mutation.

NameTypeRequiredDescription

issueIdstringrequiredID of the issue to archive

linear_issue_create#Create a new issue in Linear using the issueCreate mutation. Requires a team ID and title at minimum.9 params▾

Create a new issue in Linear using the issueCreate mutation. Requires a team ID and title at minimum.

NameTypeRequiredDescription

teamIdstringrequiredID of the team to create the issue in

titlestringrequiredTitle of the issue

assigneeIdstringoptionalID of the user to assign the issue to

descriptionstringoptionalDescription of the issue

estimatestringoptionalStory point estimate for the issue

labelIdsarrayoptionalArray of label IDs to apply to the issue

prioritystringoptionalPriority level of the issue (1-4, where 1 is urgent)

projectIdstringoptionalID of the project to associate the issue with

stateIdstringoptionalID of the workflow state to set

linear_issue_delete#Permanently delete a Linear issue by ID using the issueDelete mutation.1 param▾

Permanently delete a Linear issue by ID using the issueDelete mutation.

NameTypeRequiredDescription

issueIdstringrequiredID of the issue to delete

linear_issue_get#Get a single Linear issue by ID, including its state, assignee, team, labels, and project details.1 param▾

Get a single Linear issue by ID, including its state, assignee, team, labels, and project details.

NameTypeRequiredDescription

issueIdstringrequiredID of the issue to retrieve

linear_issue_relation_create#Create a relation between two issues. Valid types: blocks, duplicate, related, similar.3 params▾

Create a relation between two issues. Valid types: blocks, duplicate, related, similar.

NameTypeRequiredDescription

issueIdstringrequiredID of the issue

relatedIssueIdstringrequiredID of the related issue

typestringrequiredRelation type: blocks, duplicate, related, or similar

linear_issue_relation_delete#Delete an issue relation by its ID.1 param▾

Delete an issue relation by its ID.

NameTypeRequiredDescription

relationIdstringrequiredID of the issue relation to delete

linear_issue_relations_list#List all relations for a specific issue (blocks, duplicates, related, similar).1 param▾

List all relations for a specific issue (blocks, duplicates, related, similar).

NameTypeRequiredDescription

issueIdstringrequiredID of the issue to get relations for

linear_issue_search#Full-text search for issues across the workspace by query string.3 params▾

Full-text search for issues across the workspace by query string.

NameTypeRequiredDescription

querystringrequiredText to search for across issue titles and descriptions

firstintegeroptionalNumber of results to return (max 250)

teamIdstringoptionalRestrict search to a specific team ID

linear_issue_unarchive#Restore an archived issue back to active status.1 param▾

Restore an archived issue back to active status.

NameTypeRequiredDescription

issueIdstringrequiredID of the archived issue to restore

linear_issue_update#Update an existing issue in Linear. You can update title, description, priority, state, and assignee.6 params▾

Update an existing issue in Linear. You can update title, description, priority, state, and assignee.

NameTypeRequiredDescription

issueIdstringrequiredID of the issue to update

assigneeIdstringoptionalID of the user to assign the issue to

descriptionstringoptionalNew description for the issue

prioritystringoptionalPriority level of the issue (1-4, where 1 is urgent)

stateIdstringoptionalID of the workflow state to set

titlestringoptionalNew title for the issue

linear_issues_list#List issues in Linear using the issues query with simple filtering and pagination support.8 params▾

List issues in Linear using the issues query with simple filtering and pagination support.

NameTypeRequiredDescription

afterstringoptionalCursor for pagination (returns issues after this cursor)

assigneestringoptionalFilter by assignee email (e.g., 'user@example.com')

beforestringoptionalCursor for pagination (returns issues before this cursor)

firstintegeroptionalNumber of issues to return (pagination)

labelsarrayoptionalFilter by label names (array of strings)

prioritystringoptionalFilter by priority level (1=Urgent, 2=High, 3=Medium, 4=Low)

projectstringoptionalFilter by project name (e.g., 'Q4 Goals')

statestringoptionalFilter by state name (e.g., 'In Progress', 'Done')

linear_label_create#Create a new issue label in a Linear team.4 params▾

Create a new issue label in a Linear team.

NameTypeRequiredDescription

namestringrequiredLabel name

teamIdstringrequiredTeam ID to create the label in

colorstringoptionalLabel color as hex code

descriptionstringoptionalLabel description

linear_labels_list#List issue labels in the Linear workspace, optionally filtered by team.2 params▾

List issue labels in the Linear workspace, optionally filtered by team.

NameTypeRequiredDescription

firstintegeroptionalNumber of labels to return

teamIdstringoptionalFilter labels by team ID

linear_project_create#Create a new project in Linear with optional description, state, and date fields.6 params▾

Create a new project in Linear with optional description, state, and date fields.

NameTypeRequiredDescription

namestringrequiredName of the project

teamIdsarrayrequiredArray of team IDs to associate with the project

descriptionstringoptionalDescription of the project

startDatestringoptionalStart date in YYYY-MM-DD format

statestringoptionalProject state: planned, started, paused, completed, cancelled

targetDatestringoptionalTarget date in YYYY-MM-DD format

linear_project_get#Get a single Linear project by ID, including teams, members, and associated issues.1 param▾

Get a single Linear project by ID, including teams, members, and associated issues.

NameTypeRequiredDescription

projectIdstringrequiredID of the project to retrieve

linear_project_milestone_create#Create a new milestone for a project.4 params▾

Create a new milestone for a project.

NameTypeRequiredDescription

namestringrequiredName of the milestone

projectIdstringrequiredID of the project to add the milestone to

descriptionstringoptionalDescription of the milestone

targetDatestringoptionalTarget completion date (YYYY-MM-DD)

linear_project_milestone_delete#Delete a project milestone by its ID.1 param▾

Delete a project milestone by its ID.

NameTypeRequiredDescription

milestoneIdstringrequiredID of the milestone to delete

linear_project_milestone_update#Update an existing project milestone.4 params▾

Update an existing project milestone.

NameTypeRequiredDescription

milestoneIdstringrequiredID of the milestone to update

descriptionstringoptionalNew description

namestringoptionalNew name for the milestone

targetDatestringoptionalNew target date (YYYY-MM-DD)

linear_project_milestones_list#List milestones for a specific project.2 params▾

List milestones for a specific project.

NameTypeRequiredDescription

projectIdstringrequiredID of the project to list milestones for

firstintegeroptionalNumber of milestones to return

linear_project_update#Update an existing Linear project's name, description, state, or dates.6 params▾

Update an existing Linear project's name, description, state, or dates.

NameTypeRequiredDescription

projectIdstringrequiredID of the project to update

descriptionstringoptionalUpdated description of the project

namestringoptionalUpdated name of the project

startDatestringoptionalUpdated start date in YYYY-MM-DD format

statestringoptionalUpdated project state: planned, started, paused, completed, cancelled

targetDatestringoptionalUpdated target date in YYYY-MM-DD format

linear_projects_list#List all projects in the Linear workspace with pagination support.2 params▾

List all projects in the Linear workspace with pagination support.

NameTypeRequiredDescription

afterstringoptionalPagination cursor for fetching the next page

firstintegeroptionalNumber of projects to return

linear_roadmaps_list#List all roadmaps in the Linear workspace with pagination support.2 params▾

List all roadmaps in the Linear workspace with pagination support.

NameTypeRequiredDescription

afterstringoptionalPagination cursor for fetching the next page

firstintegeroptionalNumber of roadmaps to return

linear_team_create#Create a new team in the Linear workspace.5 params▾

Create a new team in the Linear workspace.

NameTypeRequiredDescription

namestringrequiredName of the team

colorstringoptionalTeam color as hex code

descriptionstringoptionalDescription of the team

keystringoptionalShort identifier key for the team (e.g. PLAT)

privatebooleanoptionalWhether the team is private

linear_team_get#Get a single Linear team by ID, including its members and workflow states.1 param▾

Get a single Linear team by ID, including its members and workflow states.

NameTypeRequiredDescription

teamIdstringrequiredID of the team to retrieve

linear_team_update#Update an existing team's name, description, or settings.4 params▾

Update an existing team's name, description, or settings.

NameTypeRequiredDescription

teamIdstringrequiredID of the team to update

colorstringoptionalNew team color as hex code

descriptionstringoptionalNew description for the team

namestringoptionalNew name for the team

linear_teams_list#List all teams in the Linear workspace with their members and pagination support.2 params▾

List all teams in the Linear workspace with their members and pagination support.

NameTypeRequiredDescription

afterstringoptionalPagination cursor for fetching the next page

firstintegeroptionalNumber of teams to return

linear_test_list#List issues in Linear using the issues query with simple filtering and pagination support.8 params▾

List issues in Linear using the issues query with simple filtering and pagination support.

NameTypeRequiredDescription

afterstringoptionalCursor for pagination (returns issues after this cursor)

assigneestringoptionalFilter by assignee email (e.g., 'user@example.com')

beforestringoptionalCursor for pagination (returns issues before this cursor)

firstintegeroptionalNumber of issues to return (pagination)

labelsarrayoptionalFilter by label names (array of strings)

prioritystringoptionalFilter by priority level (1=Urgent, 2=High, 3=Medium, 4=Low)

projectstringoptionalFilter by project name (e.g., 'Q4 Goals')

statestringoptionalFilter by state name (e.g., 'In Progress', 'Done')

linear_user_get#Retrieve a single Linear user by their ID.1 param▾

Retrieve a single Linear user by their ID.

NameTypeRequiredDescription

userIdstringrequiredID of the user to retrieve

linear_users_list#List all users in the Linear workspace with pagination support.2 params▾

List all users in the Linear workspace with pagination support.

NameTypeRequiredDescription

afterstringoptionalPagination cursor for fetching the next page

firstintegeroptionalNumber of users to return

linear_viewer_get#Get the currently authenticated Linear user (viewer), including their teams.0 params▾

Get the currently authenticated Linear user (viewer), including their teams.

linear_webhook_create#Create a new webhook for Linear events. Specify the URL and the resource types to subscribe to.6 params▾

Create a new webhook for Linear events. Specify the URL and the resource types to subscribe to.

NameTypeRequiredDescription

resourceTypesarrayrequiredList of resource types to subscribe to (e.g. Issue, Comment, Project)

urlstringrequiredThe URL to receive webhook payloads

enabledbooleanoptionalWhether the webhook is active (default: true)

labelstringoptionalHuman-readable label for the webhook

secretstringoptionalSecret token to sign the webhook payload

teamIdstringoptionalRestrict webhook to a specific team ID

linear_webhook_delete#Delete a webhook by its ID.1 param▾

Delete a webhook by its ID.

NameTypeRequiredDescription

webhookIdstringrequiredID of the webhook to delete

linear_webhook_get#Retrieve a single webhook by its ID.1 param▾

Retrieve a single webhook by its ID.

NameTypeRequiredDescription

webhookIdstringrequiredID of the webhook

linear_webhook_update#Update an existing webhook's URL, resource types, label, or enabled status.6 params▾

Update an existing webhook's URL, resource types, label, or enabled status.

NameTypeRequiredDescription

webhookIdstringrequiredID of the webhook to update

enabledbooleanoptionalEnable or disable the webhook

labelstringoptionalNew label for the webhook

resourceTypesarrayoptionalUpdated list of resource types to subscribe to

secretstringoptionalNew secret token for signing payloads

urlstringoptionalNew URL to receive webhook payloads

linear_webhooks_list#List all webhooks configured for the current workspace.2 params▾

List all webhooks configured for the current workspace.

NameTypeRequiredDescription

afterstringoptionalPagination cursor

firstintegeroptionalNumber of webhooks to return

linear_workflow_state_create#Create a new workflow state for a Linear team. Valid types: backlog, unstarted, started, completed, canceled.6 params▾

Create a new workflow state for a Linear team. Valid types: backlog, unstarted, started, completed, canceled.

NameTypeRequiredDescription

colorstringrequiredColor of the state as a hex code

namestringrequiredName of the workflow state

teamIdstringrequiredID of the team to create the state in

typestringrequiredState type: backlog, unstarted, started, completed, or canceled

descriptionstringoptionalOptional description of the state

positionnumberoptionalPosition of the state in the workflow

linear_workflow_state_get#Retrieve a single workflow state by its ID.1 param▾

Retrieve a single workflow state by its ID.

NameTypeRequiredDescription

stateIdstringrequiredID of the workflow state

linear_workflow_state_update#Update an existing workflow state in Linear.4 params▾

Update an existing workflow state in Linear.

NameTypeRequiredDescription

stateIdstringrequiredID of the workflow state to update

colorstringoptionalNew color as hex code

descriptionstringoptionalNew description for the state

namestringoptionalNew name for the state

linear_workflow_states_list#List workflow states in the Linear workspace, optionally filtered by team.2 params▾

List workflow states in the Linear workspace, optionally filtered by team.

NameTypeRequiredDescription

firstintegeroptionalNumber of workflow states to return

teamIdstringoptionalFilter by team ID