Skip to navigation
Integrations

Linear integration

Connect Linear so that an Agent can create, update, and find issues, list teams and projects, and add comments. You can add Linear tools to an Agent or to a prompt step in a Flow. Linear does not have a dedicated Flow step.

Before you begin

Create a personal API key in Linear Settings > API. Linear API keys start with lin_api_. Treat the key as a password.

Connect Linear

To connect Linear and add its tools to an Agent, follow these steps:

  1. Open the Agent, and click Add tool.
  2. Find Linear, and click Set up.
  3. Paste your key in the API key field.
  4. Click Connect Linear. Runtype adds all Linear tools to the Agent.
  5. Optional: In the Linear row, clear the tools that the Agent does not need.
  6. Click Save version.

Runtype saves the key to your account in the current organization. Your Agents and prompt steps with Linear tools use it. Runtype doesn’t check the key when you save it, so verify the connection.

Verify the connection

Run the Agent and ask it to list your Linear teams. If the Agent returns your teams, the key works. The result also gives you the team IDs that create_issue needs.

Available tools

The following table lists the Linear tools. In Agent instructions, refer to a tool by the name that the model sees, such as linear_create_issue.

ToolWhat it does
create_issueCreates an issue. Requires a title and a team ID. Optionally sets a description, assignee, priority, state, labels, project, and estimate.
update_issueChanges an issue’s title, description, assignee, priority, or state. It cannot change labels, project, or estimate.
search_issuesLists issues, filtered by team ID or assignee ID. Returns 25 issues by default. Set limit to return up to 100.
get_issueGets one issue by ID or by identifier, such as ENG-123.
list_teamsLists the teams in the workspace, with their IDs.
list_projectsLists projects, optionally filtered by team ID.
add_commentAdds a comment to an issue.

Work with Linear IDs

Linear tools take IDs, not names, for teams, users, workflow states, labels, and projects. Add list_teams with create_issue so that the Agent can find the team ID. Add list_projects if the Agent sets projects.

No Linear tool lists users, workflow states, or labels. To assign issues, change their state, or add labels, copy the IDs from Linear and put them in the Agent’s instructions.

Priority is a number: 0 None, 1 Urgent, 2 High, 3 Medium, 4 Low.

search_issues doesn’t filter by search text or state name. It accepts a query and a state value but ignores them, and returns unfiltered issues for the team or assignee. To find a specific issue, use get_issue with its identifier, or tell the Agent to check the titles in the results.

Connect with the API

To save the key with the API, send it to the Linear credentials endpoint. The API key that you use needs the INTEGRATIONS:WRITE scope.

Save a Linear key
curl -X POST https://api.runtype.com/v1/integrations/linear/credentials \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "lin_api_YOUR_LINEAR_KEY"}'

Replace the following:

  • YOUR_API_KEY: your Runtype API key.
  • lin_api_YOUR_LINEAR_KEY: your Linear API key.

A request without apiKey fails with apiKey is required for Linear. To replace the key, send the request again with the new key.

By default, the key applies to all environments. To save a key for one environment, add "environment": "development" or "environment": "production" to the body. A run uses the key for its environment. If that environment has no key, the run uses the all-environments key.

To attach Linear tools to an Agent, add their IDs to the Agent’s tools.toolIds. Linear tool IDs use the form builtin:linear:<tool>:

Agent tools
{
  "tools": {
    "toolIds": ["builtin:linear:list_teams", "builtin:linear:create_issue"]
  }
}

Use cases

Use Linear tools for the following tasks:

  • Bug reporting: Create issues from customer feedback.
  • Feature requests: Track requests from chat conversations.
  • Escalations: Create urgent issues when a run finds a problem.
  • Monitoring: Log anomalies from scheduled runs.

Troubleshooting

  • Linear API error: ...: Linear rejected the request. If the message is about authentication, the key is wrong or revoked. Create a new key in Linear, and save it again. Otherwise, check the IDs that the Agent sent.
  • MCP server "linear" not configured: No key exists for the run’s environment. The message points to Settings > Integrations, but Linear is not listed there. Connect Linear from the Agent’s Add tool list, or save a key with the API for all environments or for the environment that the run uses.
  • The Agent can’t create an issue: create_issue requires a team ID. Add list_teams to the Agent, or put the team ID in its instructions.

Remove Linear access

To stop an Agent from using Linear, remove its Linear tools in the Agent editor, and click Save version.

To stop all Linear access, revoke the API key in Linear. After that, Linear tools return a Linear API error.

To delete the stored key from Runtype, send a DELETE request to /v1/integrations/linear/credentials. Without a query parameter, the request deletes the all-environments key. To delete a key for one environment, add ?environment=development or ?environment=production.

Next steps