FastAPI service for integrating with Linear.app via GraphQL API. This service allows you to create, update, and manage Linear issues programmatically.

Linear Integration Service

FastAPI service for integrating with Linear.app via GraphQL API. This service allows you to create, update, and manage Linear issues programmatically.

Features

✅ Create Linear issues
✅ Update existing issues
✅ Get teams, projects, users, and states
✅ Full GraphQL API integration
✅ Type-safe Pydantic models

Setup

1. Get Linear API Key

Go to Linear.app → Settings → API
Create a Personal API Key
Copy the API key

2. Environment Variables

Create a .env file or set environment variables:

LINEAR_API_KEY=lin_api_xxxxxxxxxxxxx
LINEAR_WORKSPACE_ID=optional_workspace_id  # Optional, will be auto-detected
PORT=8003

3. Install Dependencies

pip install -r requirements.txt

4. Run the Service

# Development
uvicorn main:app --reload --port 8003

# Production
uvicorn main:app --host 0.0.0.0 --port 8003

API Endpoints

Health Check

GET /health

Returns service health status and Linear connection status.

Create Issue

POST /create-issue

Request Body:

{
    "title": "Fix PDF parsing bug",
    "description": "The PDF parser fails on certain file types",
    "team_id": "team-id-here",
    "priority": 2,
    "assignee_id": "user-id-here",
    "project_id": "project-id-here",
    "due_date": "2024-12-31"
}

Response:

{
    "success": true,
    "issue": {
        "id": "issue-id",
        "identifier": "ENG-123",
        "title": "Fix PDF parsing bug",
        "description": "...",
        "priority": 2,
        "state": {
            "id": "state-id",
            "name": "Todo",
            "type": "unstarted"
        },
        "assignee": {
            "id": "user-id",
            "name": "John Doe",
            "email": "john@example.com"
        },
        "team": {
            "id": "team-id",
            "name": "Engineering",
            "key": "ENG"
        },
        "url": "https://linear.app/workspace/issue/ENG-123"
    }
}

Get Teams

GET /teams

Returns all teams in the workspace.

Get Projects

GET /projects

Returns all projects in the workspace.

Get Issue

GET /issue/{issue_id}

Returns a specific issue by ID.

Update Issue

POST /update-issue/{issue_id}

Request Body:

{
    "title": "Updated title",
    "priority": 1,
    "state_id": "in-progress-state-id"
}

All fields are optional - only provided fields will be updated.

Get Users

GET /users

Returns all users in the workspace.

Get States

GET /states?team_id={team_id}

Returns all workflow states for a specific team.

Usage Examples

Create an Issue from Cursor

import requests

response = requests.post(
    "http://localhost:8003/create-issue",
    json={
        "title": "Implement new feature",
        "description": "Add support for new file format",
        "team_id": "your-team-id",
        "priority": 2
    }
)

issue = response.json()
print(f"Created issue: {issue['issue']['identifier']}")

Get Available Teams

import requests

response = requests.get("http://localhost:8003/teams")
teams = response.json()

for team in teams:
    print(f"{team['name']} ({team['id']})")

Docker

Build

docker build -t linear-service .

Run

docker run -p 8003:8003 \
  -e LINEAR_API_KEY=your_api_key \
  linear-service

Deployment to GCP Cloud Run

See cloudbuild.yaml for Cloud Build configuration.

gcloud builds submit --config cloudbuild.yaml

Priority Levels

0 = No priority
1 = Urgent
2 = High
3 = Medium
4 = Low

GraphQL API

This service uses Linear's GraphQL API directly. For more advanced queries, you can extend the LinearClient class with additional GraphQL queries.

Error Handling

All endpoints return appropriate HTTP status codes:

200 = Success
400 = Bad Request (validation errors)
404 = Not Found
500 = Internal Server Error
503 = Service Unavailable (Linear client not initialized)

License

MIT

Linear Integration Service

On this page