Linear Toolkit
The Linear toolkit connects a Linear workspace to agents and workflows using a personal API key and lets you list and search issues, create and update issues and projects, manage labels and comments, inspect cycles and workflow states, and browse teams and users. The key inherits the creating user's access and is not independently scoped.
Prerequisites
- An active Linear workspace.
- Permission in Linear to view the teams, issues, and projects the agent or workflow requires.
- A Linear personal API key — go to Account → Security & access in Linear or visit linear.app/settings/api. Copy the key when it is displayed (keys start with
lin_api_). - Prefer a dedicated, least-privilege automation user rather than a workspace administrator.
Linear personal API keys inherit the full permissions of the user who created them. Write actions (Create Issue, Update Issue, Create Project, Create Label, Add Comment) change live Linear data immediately and are not confirmation-gated. Use a dedicated service account with access limited to the teams the agent should use. Never expose keys in prompts, chat, tickets, screenshots, or documentation.
Setup
- Create a Linear personal API key
In Linear, go to Account → Security & access and create a personal API key. Give it a recognizable label, choose the minimum permissions needed, and copy the key immediately.
- Open an agent or workflow
Open an agent and add the Linear toolkit under Toolkits, or add a Linear step to a workflow.
- Create a saved connection
In the Linear step, choose + New under Select saved connection. Enter a Connection Name and the Personal API Key. Save the connection.
- Set a default team (agents only)
Optionally set a Default Team ID (a team key such as
ENGor a unique ID) in the agent configuration. This is used when Create Issue or Create Project does not receive an explicit team. - Test the connection
Run Get Current User to confirm the key is linked to the intended Linear user. Then run List Teams to confirm workspace access before enabling write actions.
Available tools
Auth and Users
| Tool | Description |
|---|---|
| Get Current User | Returns the Linear user that owns the connected API key. Use as a smoke test after connecting. |
| List Users | Lists workspace users. Use to find assignee IDs before creating or updating issues. |
Teams
| Tool | Description |
|---|---|
| List Teams | Lists teams in the workspace including team keys, issue counts, and cycle settings. |
| Get Team | Returns one team including its workflow states. Use to find state IDs before updating issues. |
Issues
| Tool | Description |
|---|---|
| List Issues | Lists issues with optional filters for team, assignee, state type, priority, and project. |
| Get Issue | Returns one issue by unique ID or identifier (e.g. ENG-123) including comments and sub-issues. |
| Search Issues | Full-text search across issue titles and descriptions. |
| Create Issue | Creates an issue in a team with optional description, priority, assignee, project, and labels. |
| Update Issue | Updates an issue's title, description, priority, state, assignee, project, or labels. |
| List My Issues | Lists issues assigned to the authenticated Linear user. |
Projects
| Tool | Description |
|---|---|
| List Projects | Lists projects with status, progress, and issue counts. |
| Get Project | Returns one project including recent updates and associated teams. |
| Create Project | Creates a project associated with one or more teams. |
Labels
| Tool | Description |
|---|---|
| List Labels | Lists issue labels with unique IDs for use in Create Issue and Update Issue. |
| Create Label | Creates a new issue label with optional color and description. |
Comments
| Tool | Description |
|---|---|
| List Comments | Lists comments on an issue. Use the issue unique ID (not the short identifier) if filtering fails. |
| Add Comment | Adds a markdown comment to an issue. |
Cycles
| Tool | Description |
|---|---|
| List Cycles | Lists cycles (sprints) with derived status (active, upcoming, completed) and progress. |
| Get Cycle | Returns one cycle and up to 100 of its issues. |
Workflow
| Tool | Description |
|---|---|
| List Workflow States | Lists workflow states, optionally filtered by team. Use to find state IDs before Update Issue. |
Use cases
- List open issues for a team or assignee and summarize them before a standup.
- Look up a specific issue by identifier (e.g. ENG-123), read its comments, and add a follow-up note.
- Create an issue from a chat or form submission and assign it to the right team member.
- Find the active cycle and inspect its issue progress and completion rate.
- Update an issue's state and assignee after a workflow step confirms a task is complete.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Linear not visible in the toolkit picker | The toolkit is not enabled for the environment or project. | Ask a Super Admin to enable the toolkit and refresh the picker. |
| No Linear API key available | The action ran without a key. | Select a saved connection or enter the API key on the step. |
| Authentication failed | The key is incomplete, revoked, or member API keys are disabled in the workspace. | Confirm the key is valid and that the workspace allows member API keys. |
| Team required to create an issue or project | Create Issue and Create Project require a team. | Provide a Team ID on the action, or set a Default Team ID in the agent configuration. |
| Issue or comment not found | An incorrect ID was used, or the key cannot see the issue. | Use the unique ID from Get Issue or List Issues — short identifiers may not work in all actions. |
| No issues returned | Filters are too restrictive or the key cannot see those issues. | Check team, assignee, state type, and priority filters. Confirm the key has access to those issues in Linear. |
| Rate limit error | Personal API keys are limited to 2,500 requests per hour. | Wait for the rate-limit window to reset. Reduce list limits and avoid polling. |