Linear

Authentication Type: API Key
Description: Issue tracking and project management platform for modern software development teams.

Issues

Create, update, and manage Linear issues for tracking tasks, bugs, and feature requests.

Create Issue

Create a new Linear issue with title, description, and optional metadata like assignee, project, labels, and due date.

Operation Type: Mutation (Write)

Parameters:

• teamId string (required): The Linear team ID where the issue will be created. You can get team IDs from the teams endpoint or Linear UI
• title string (required): The title/name of the issue. Should be concise and descriptive of the task or problem
• description string (nullable): Description or body text of the issue. Can include markdown formatting, details, acceptance criteria, etc. Use null if no description is needed
• projectId string (nullable): Linear project ID to associate this issue with. Use this to group related issues under a project. Use null if not associating with a project
• assigneeId string (nullable): Linear user ID to assign this issue to. The assignee will be responsible for completing the issue. Use null if not assigning to anyone
• parentId string (nullable): Parent issue ID to create this as a sub-issue. Use this to break down larger issues into smaller tasks. Use null if this is not a sub-issue
• dueDate string (nullable): Due date for the issue in ISO 8601 format (YYYY-MM-DD). When the issue should be completed by. Use null if no due date is needed
• labelIds array of strings (nullable): Array of Linear label IDs to categorize or tag this issue. Use labels to organize and filter issues. Use null if no labels are needed
• cycleId string (nullable): Linear cycle ID to add this issue to the current development cycle/sprint. Use null if not adding to a cycle

Returns:

• id string: Linear issue ID
• identifier string: Human-readable issue identifier (e.g., "ENG-123")
• title string: Issue title
• description string (nullable): Issue description
• priority number: Issue priority level
• createdAt string (nullable): Issue creation date
• updatedAt string (nullable): Last update date

Example Usage:

{
  "teamId": "team_abc123",
  "title": "Implement user authentication system",
  "description": "Create a comprehensive authentication system with JWT tokens, password hashing, and session management. Include login/logout functionality and password reset flow.",
  "projectId": "project_def456",
  "assigneeId": "user_ghi789",
  "parentId": null,
  "dueDate": "2024-02-15",
  "labelIds": ["label_backend", "label_security"],
  "cycleId": "cycle_jkl012"
}

Update Issue

Update an existing Linear issue by modifying its properties such as title, description, assignee, priority, or status. Can also add comments to the issue during the update.

Operation Type: Mutation (Write)

Parameters:

• id string (required): The Linear issue ID to update. This is the unique identifier for the existing issue you want to modify
• teamId string (nullable): The Linear team ID where the issue will be created. Use null if not updating the team
• title string (nullable): The title/name of the issue. Use null if no title update is needed
• description string (nullable): Description or body text of the issue. Use null if no description update is needed
• projectId string (nullable): Linear project ID to associate this issue with. Use null if not updating project association
• assigneeId string (nullable): Linear user ID to assign this issue to. Use null if not updating assignee
• parentId string (nullable): Parent issue ID to create this as a sub-issue. Use null if not updating parent relationship
• dueDate string (nullable): Due date for the issue in ISO 8601 format (YYYY-MM-DD). Use null if not updating due date
• labelIds array of strings (nullable): Array of Linear label IDs to categorize or tag this issue. Use null if not updating labels
• cycleId string (nullable): Linear cycle ID to add this issue to the current development cycle/sprint. Use null if not updating cycle
• comment string (nullable): Comment to add to the issue. This will create a new comment with the provided text. Can include markdown formatting and mentions. Use null if no comment is needed
• priority string (nullable): Priority level for the issue. Options: "No Priority", "Urgent", "High", "Normal", "Low". Use null if not updating priority

Returns:

• id string: Linear issue ID
• identifier string: Human-readable issue identifier
• title string: Issue title
• description string (nullable): Issue description
• priority number: Issue priority level
• createdAt string (nullable): Issue creation date
• updatedAt string (nullable): Last update date

Example Usage:

{
  "id": "issue_xyz789",
  "teamId": null,
  "title": null,
  "description": null,
  "projectId": null,
  "assigneeId": "user_abc123",
  "parentId": null,
  "dueDate": "2024-02-20",
  "labelIds": null,
  "cycleId": null,
  "comment": "Reassigning to @john for completion. Updated due date to accommodate testing phase.",
  "priority": "High"
}

Get Issue

Retrieve details of a specific Linear issue including its title, description, and current metadata.

Operation Type: Query (Read)

Parameters:

• id string (required): The Linear issue ID to retrieve. This will return the issue details including title, description, and other metadata

Returns:

• id string: Linear issue ID
• identifier `string**: Human-readable issue identifier
• title string: Issue title
• description string (nullable): Issue description
• priority number: Issue priority level
• createdAt string (nullable): Issue creation date
• updatedAt string (nullable): Last update date

Example Usage:

{
  "id": "issue_xyz789"
}

List Issues

Retrieve multiple Linear issues with optional filtering by team, assignee, state, priority, labels, and date ranges.

Operation Type: Query (Read)

Parameters:

• teamId string (nullable): Filter issues by Linear team ID. Use null to search across all teams
• assigneeId string (nullable): Filter issues by assignee user ID. Use null to include issues with any assignee
• stateId string (nullable): Filter issues by state ID (e.g., "In Progress", "Done", "Backlog"). Use null to include issues in any state
• priority string (nullable): Filter issues by priority. Options: "No Priority", "Urgent", "High", "Normal", "Low". Use null to include issues with any priority
• labelIds array of strings (nullable): Filter issues by label IDs. Use null to include issues with any labels
• createdAtGte string (nullable): Filter issues created on or after this date. ISO 8601 format. Use null to not filter by creation date
• createdAtLte string (nullable): Filter issues created on or before this date. ISO 8601 format. Use null to not filter by creation date
• updatedAtGte string (nullable): Filter issues updated on or after this date. ISO 8601 format. Use null to not filter by update date
• updatedAtLte string (nullable): Filter issues updated on or before this date. ISO 8601 format. Use null to not filter by update date
• first number (nullable): Maximum number of issues to return. Use null for default limit
• includeArchived boolean (nullable): Whether to include archived issues. Use null for default behavior

Returns:

• issues array of objects: Array of Linear issues with same structure as individual issue

Example Usage:

{
  "teamId": "team_abc123",
  "assigneeId": null,
  "stateId": null,
  "priority": "High",
  "labelIds": ["label_backend", "label_security"],
  "createdAtGte": "2024-01-01T00:00:00.000Z",
  "createdAtLte": null,
  "updatedAtGte": null,
  "updatedAtLte": null,
  "first": 50,
  "includeArchived": false
}

Add Label to Issue

Attach a label to an existing Linear issue for categorization, priority marking, or workflow organization.

Operation Type: Mutation (Write)

Parameters:

• issueId string (required): The Linear issue ID to add the label to
• labelId string (required): The Linear label ID to add to the issue

Returns:

• Empty object on success

Example Usage:

{
  "issueId": "issue_xyz789",
  "labelId": "label_urgent"
}

Remove Label from Issue

Remove a previously attached label from a Linear issue to update its categorization or workflow status.

Operation Type: Mutation (Write)

Parameters:

• issueId string (required): The Linear issue ID to remove the label from
• labelId string (required): The Linear label ID to remove from the issue

Returns:

• Empty object on success

Example Usage:

{
  "issueId": "issue_xyz789",
  "labelId": "label_urgent"
}

Attach Link to Issue

Attach a URL link to an existing Linear issue. Useful for linking documentation, external resources, or related web content to issues.

Operation Type: Mutation (Write)

Parameters:

• issueId string (required): The Linear issue ID to attach the URL to
• url string (required): The URL to attach to the issue. Should be a valid URL like "https://example.com"
• title string (nullable): Optional title for the link attachment. If not provided, Linear will use the page title from the URL. Use null to let Linear auto-generate the title
• createAsUser string (nullable): Create attachment as a user with the provided name. This option is only available to OAuth applications creating attachments in actor=app mode. Use null for default behavior
• displayIconUrl string (nullable): Provide an external user avatar URL. Can only be used in conjunction with the createAsUser option. Use null for default behavior

Returns:

• success boolean: Whether the attachment was successful
• attachment object (nullable): Attachment details
  • id string: Attachment ID
  • url string: Attached URL
  • title string (nullable): Attachment title

Example Usage:

{
  "issueId": "issue_xyz789",
  "url": "https://docs.example.com/authentication-guide",
  "title": "Authentication Implementation Guide",
  "createAsUser": null,
  "displayIconUrl": null
}

Common Use Cases

Agile Development Workflow:

• Create issues for user stories, bugs, and technical tasks with proper team assignment and project organization
• Update issue status and priority as work progresses through development cycles and sprints
• Filter and list issues by assignee, labels, and date ranges for sprint planning and progress tracking

Project Management:

• Organize issues under projects with parent-child relationships for feature breakdown and epic management
• Add labels for categorization by feature area, priority, or development phase
• Set due dates and track progress for milestone-based project delivery

Team Collaboration:

• Add comments to issues for progress updates, technical discussions, and requirement clarification
• Attach documentation links and external resources for context and reference materials
• Filter issues by team and assignee for workload distribution and individual progress tracking

Issue Tracking and Maintenance:

• Retrieve specific issues for detailed analysis and status updates
• Add and remove labels dynamically as issues move through different workflow states
• Track issue creation and update patterns for team productivity analysis and process improvement