Linear API Essential Guide

What type of API does Linear provide?

Based on the search results, Linear has a GraphQL API. The key points are:

1. Linear's public API is built using GraphQL. It's the same API they use internally for developing their applications.

2. The Linear API endpoint is https://api.linear.app/graphql.

3. Linear provides a SDK that exposes the Linear GraphQL schema and makes it easy to access models and perform mutations.

4. GraphQL APIs allow clients to request exactly the data they need in a single request, which can be more efficient than REST APIs in some cases.

5. GraphQL APIs have a typed schema that publishes in advance what queries are available, improving discoverability.

6. GraphQL APIs typically use a single evolving version rather than multiple API versions like REST.

7. GraphQL provides detailed error messages that include all the resolvers and refer to the exact query part at fault.

Some key advantages of GraphQL mentioned in the results include:

• Flexible data fetching
• Strongly typed schema
• Single endpoint
• No versioning required
• Detailed error messages
• Fits graph-like data well

In summary, Linear uses a GraphQL API, which provides a flexible and efficient way for clients to request exactly the data they need from Linear's platform.

Does the Linear API have webhooks?

Yes, Linear provides webhooks as part of their official API. Linear supports "data change webhooks" for various models and events, including issues, issue attachments, issue comments, issue labels, comment reactions, projects, project updates, cycles, issue SLA, and OAuthApp revoked.

Key details about Linear webhooks:

• Webhooks allow you to receive HTTP push notifications when data is created or updated in Linear.
• Webhooks are specific to an Organization, but can be configured for all public teams or a single team.
• Webhook payloads include information in both HTTP headers and the request body.
• The payload format reflects the corresponding GraphQL entity.
• Linear provides security features like HMAC signatures and IP address validation for webhooks.
• Webhooks can be configured via the Linear UI or programmatically through the GraphQL API.
• Common use cases include triggering CI builds, performing calculations on issue data, or sending messages on specific conditions.

To set up webhooks, you can use the API settings in Linear to configure the webhook URL, label, and which event types to subscribe to.

Rate Limits and other limitations

Here are the key points about the API Rate Limits for the Linear API:

Rate Limits for Different Authentication Methods

• API key authentication: 1,500 requests per hour per user
• OAuth app authentication: 500 requests per hour per user/app
• Unauthenticated requests: 60 requests per hour per IP address

API Request Complexity Limits

Linear also implements complexity-based rate limiting:

• API key authentication: 250,000 complexity points per hour per user
• OAuth app authentication: 200,000 complexity points per hour per user/app
• Unauthenticated requests: 10,000 complexity points per hour per IP address

Key Considerations

• Linear uses a leaky bucket algorithm for rate limiting, meaning tokens are refilled at a constant rate
• The API returns rate limit information in response headers, including:
  • Remaining requests/complexity points
  • Rate limit reset time
  • Maximum allowed requests/complexity
• Exceeding rate limits will result in a 429 Too Many Requests error

Best Practices

• Use webhooks instead of polling for real-time updates
• Filter and paginate results efficiently to reduce API usage
• Authenticate requests when possible to get higher rate limits
• Monitor rate limit headers to avoid exceeding limits

Additional Notes

• Rate limits may evolve over time based on usage patterns
• Higher limits can be requested from Linear support for temporary needs
• The Linear SDK is recommended for interacting with the API

By following these guidelines and best practices, developers can effectively work within Linear's API rate limits while building integrations and applications.

Latest API Version

Based on the search results provided, here are the key points about the most recent version of the Linear API:

Current API Version

The search results do not explicitly mention a specific version number for the Linear API. However, they provide information about the current state of the API:

• Linear's public API is built using GraphQL.
• It's the same API that Linear uses internally for developing their applications.

Key Features

1. Full support for querying and mutating all entities.
2. Real-time updates: Any mutations made via the API are observed in real-time by all clients.

Documentation and Resources

• Detailed API documentation is available at https://developers.linear.app/docs/graphql/working-with-the-graphql-api.
• For more in-depth documentation, developers can visit developers.linear.app.

Access and Authentication

• Users can create personal API keys in the API section under general settings.
• These keys allow querying and updating data available to the user's account.

Webhooks

• Linear also offers webhook support for issues and comments.
• Webhooks can be configured to receive HTTP(S) push notifications when data is created or updated.
• More information on webhooks can be found in the webhook documentation linked in the general settings.

Community Support

• For questions not answered in the documentation, users can post in the #api channel in Linear's Slack community.

While the search results don't mention a specific version number, they indicate that the API is actively maintained and updated. For the most up-to-date information on the Linear API version, it's recommended to check the official Linear developers documentation at developers.linear.app.

How to get a Linear developer account and API Keys?

Here's how to get a developer account for Linear to create an API integration:

Key Steps

1. Create a Linear account or log in to your existing account at linear.app.

2. Go to your workspace settings by clicking on your username in the top-left corner and selecting "Workspace settings".

3. In the settings menu on the left, scroll down and click on "API".

4. On the API page, you'll see options to create API keys and manage OAuth applications.

5. To create a personal API key:

   • Click "Create new API key"
   • Add a label for the key
   • Copy and securely store the generated API key, as Linear will only show it once

6. To set up OAuth for an application:

   • Go to the OAuth section
   • Click "New OAuth application"
   • Fill in the required details for your app

Key Points to Consider

• Linear uses a GraphQL API for developers to interact with data.
• There are different authentication methods available:
  • Personal API keys for simpler integrations
  • OAuth 2.0 for more complex applications that need user authorization
• Be aware of rate limits when using the API. Limits vary based on authentication method.
• Linear provides webhooks for real-time notifications of data changes.
• Review the full API documentation at developers.linear.app for more details on using the API.

Best Practices

• Store API keys securely and never expose them in client-side code.
• Use OAuth 2.0 for applications that need to access user data on behalf of multiple users.
• Implement proper error handling for API responses.
• Stay within rate limits to avoid disruptions to your integration.
• Consider using Linear's official SDK for easier API interactions in JavaScript/TypeScript projects.

By following these steps and best practices, you'll be able to set up a developer account and create API integrations with Linear. Remember to thoroughly review the API documentation for the most up-to-date information on using Linear's developer tools.

What can you do with the Linear API?

Based on the information provided in the search results, here's a list of data models you can interact with using the Linear API, along with what is possible for each model:

Issues

• Create new issues
• Edit existing issues
• Query issue data
• Receive real-time updates via webhooks
• Perform similarity searches using vector representations
• Attach files and images to issues
• Filter issues based on various criteria

Issue Attachments

• Add attachments to issues
• Query attachment data
• Receive updates via webhooks

Issue Comments

• Create new comments
• Edit existing comments
• Query comment data
• Receive real-time updates via webhooks

Issue Labels

• Create and manage labels
• Associate labels with issues
• Query label data
• Receive updates via webhooks

Comment Reactions

• Add reactions to comments
• Query reaction data
• Receive updates via webhooks

Projects

• Create and manage projects
• Associate issues with projects
• Query project data
• Receive real-time updates via webhooks

Project Updates

• Create project updates
• Query update data
• Receive updates via webhooks

Cycles

• Create and manage cycles
• Associate issues with cycles
• Query cycle data
• Receive updates via webhooks

Teams

• Query team data
• Configure webhooks for specific teams

Organizations

• Query organization data
• Manage webhook configurations at the organization level

Users

• Query user data (e.g., current user information)

SLAs (Service Level Agreements)

• Manage and query SLA data for issues
• Receive updates via webhooks

OAuth Applications

• Manage OAuth application settings
• Receive webhook notifications for OAuth-related events (e.g., app revoked)

Key Points to Consider:

• The Linear API is built using GraphQL, allowing for flexible querying and mutation of data.
• Authentication is required for accessing the API and viewing assets like images.
• Webhooks can be configured to receive real-time updates for various data models.
• The Linear SDK provides a strongly-typed interface for interacting with the API in TypeScript/JavaScript environments.
• Vector search capabilities are available for similarity searches on issues.

Best Practices:

• Use the Linear SDK for easier interaction with the API in TypeScript/JavaScript projects.
• Implement proper authentication using either API keys or OAuth 2.0.
• When working with large datasets, consider using pagination and filtering to optimize API requests.
• For real-time updates, use webhooks instead of frequent polling when possible.
• Be mindful of rate limits when making API requests.

This list covers the main data models and interactions possible with the Linear API based on the provided information. The API allows for comprehensive management and querying of project-related data, enabling developers to build powerful integrations and extensions to Linear's functionality.