0
# Core Client Operations
1

2
The Linear SDK provides comprehensive client functionality for authenticated access to the Linear GraphQL API through the `LinearClient` class and underlying GraphQL infrastructure.
3

4
## Capabilities
5

6
### LinearClient
7

8
Main client class that provides authenticated access to all Linear API operations.
9

10
```typescript { .api }
11
/**
12
 * Main Linear API client that extends LinearSdk with authentication and error handling
13
 */
14
class LinearClient extends LinearSdk {
15
  /**
16
   * Creates a Linear API client
17
   * @param options - Client configuration options including authentication
18
   */
19
  constructor(options: LinearClientOptions);
20

21
  /** Parsed client configuration options */
22
  options: LinearClientParsedOptions;
23
  /** Underlying GraphQL client for low-level operations */
24
  client: LinearGraphQLClient;
25
}
26

27
interface LinearClientOptions extends RequestInit {
28
  /** Personal API token generated from https://linear.app/settings/account/security */
29
  apiKey?: string;
30
  /** The access token returned from OAuth endpoints */
31
  accessToken?: string;
32
  /** The URL to the Linear GraphQL API (defaults to production) */
33
  apiUrl?: string;
34
}
35

36
interface LinearClientParsedOptions extends RequestInit {
37
  /** The URL to the Linear GraphQL API defaulted to production */
38
  apiUrl: string;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { LinearClient } from "@linear/sdk";
46

47
// Using API key authentication
48
const client = new LinearClient({
49
  apiKey: "lin_api_your_api_key_here"
50
});
51

52
// Using OAuth access token
53
const client = new LinearClient({
54
  accessToken: "Bearer your_oauth_token_here"
55
});
56

57
// Custom API URL and additional options
58
const client = new LinearClient({
59
  apiKey: "lin_api_your_api_key_here",
60
  apiUrl: "https://api.linear.app/graphql",
61
  headers: {
62
    "Custom-Header": "value"
63
  }
64
});
65
```
66

67
### LinearGraphQLClient
68

69
Low-level GraphQL client for making direct requests to the Linear API.
70

71
```typescript { .api }
72
/**
73
 * Create an isomorphic GraphQL client for Linear API requests
74
 */
75
class LinearGraphQLClient {
76
  /**
77
   * Creates a GraphQL client
78
   * @param url - Base URL to send requests to
79
   * @param options - Request options and headers
80
   */
81
  constructor(url: string, options?: RequestInit);
82

83
  /**
84
   * Execute a GraphQL request and return the data
85
   * @param document - GraphQL document node or query string
86
   * @param variables - Variables to pass to the query
87
   * @param requestHeaders - Additional headers for this request
88
   * @returns Promise resolving to the response data
89
   */
90
  request<Data, Variables extends Record<string, unknown>>(
91
    document: DocumentNode | string,
92
    variables?: Variables,
93
    requestHeaders?: RequestInit["headers"]
94
  ): Promise<Data>;
95

96
  /**
97
   * Execute a raw GraphQL request and return the full response
98
   * @param query - GraphQL query string
99
   * @param variables - Variables to pass to the query
100
   * @param requestHeaders - Additional headers for this request
101
   * @returns Promise resolving to the raw response
102
   */
103
  rawRequest<Data, Variables extends Record<string, unknown>>(
104
    query: string,
105
    variables?: Variables,
106
    requestHeaders?: RequestInit["headers"]
107
  ): Promise<LinearRawResponse<Data>>;
108

109
  /**
110
   * Set a single request header
111
   * @param key - Header name
112
   * @param value - Header value
113
   * @returns This client instance for chaining
114
   */
115
  setHeader(key: string, value: string): LinearGraphQLClient;
116

117
  /**
118
   * Set multiple request headers
119
   * @param headers - Headers object
120
   * @returns This client instance for chaining
121
   */
122
  setHeaders(headers: RequestInit["headers"]): LinearGraphQLClient;
123
}
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
import { LinearGraphQLClient } from "@linear/sdk";
130

131
// Create a GraphQL client
132
const graphqlClient = new LinearGraphQLClient("https://api.linear.app/graphql", {
133
  headers: {
134
    Authorization: "lin_api_your_api_key_here"
135
  }
136
});
137

138
// Execute a query
139
const data = await graphqlClient.request(`
140
  query GetIssues($first: Int) {
141
    issues(first: $first) {
142
      nodes {
143
        id
144
        title
145
        state {
146
          name
147
        }
148
      }
149
    }
150
  }
151
`, { first: 10 });
152

153
// Get raw response with metadata
154
const rawResponse = await graphqlClient.rawRequest(`
155
  query { viewer { id name email } }
156
`);
157

158
console.log(rawResponse.status); // HTTP status
159
console.log(rawResponse.headers); // Response headers
160
console.log(rawResponse.data); // GraphQL data
161
```
162

163
### Request Base Class
164

165
Base class providing core request functionality and pagination helpers.
166

167
```typescript { .api }
168
/**
169
 * Base class to provide a request function and utilities
170
 */
171
class Request {
172
  /**
173
   * Creates a new request instance
174
   * @param request - Function to call the GraphQL client
175
   */
176
  constructor(request: LinearRequest);
177

178
  /**
179
   * Helper to paginate over all pages of a given connection query
180
   * @param fn - The query function to paginate
181
   * @param args - The arguments to pass to the query
182
   * @returns Promise resolving to all nodes across pages
183
   */
184
  async paginate<T extends Node, U>(
185
    fn: (variables: U) => LinearFetch<Connection<T>>,
186
    args: U
187
  ): Promise<T[]>;
188
}
189
```
190

191
### GraphQL Client Error
192

193
Error class for GraphQL-specific request failures.
194

195
```typescript { .api }
196
/**
197
 * Error class for GraphQL client request failures
198
 */
199
class GraphQLClientError<Data, Variables extends Record<string, unknown>> extends Error {
200
  /** Raw response from the Linear API */
201
  response: LinearRawResponse<Data>;
202
  /** Request context that caused the error */
203
  request: GraphQLRequestContext<Variables>;
204

205
  /**
206
   * Creates a GraphQL client error
207
   * @param response - The raw response from the Linear API
208
   * @param request - Information about the request resulting in the error
209
   */
210
  constructor(response: LinearRawResponse<Data>, request: GraphQLRequestContext<Variables>);
211
}
212
```
213

214
## Type Definitions
215

216
```typescript { .api }
217
/** Function type for making GraphQL requests */
218
type LinearRequest = <Response, Variables extends Record<string, unknown>>(
219
  doc: DocumentNode,
220
  variables?: Variables
221
) => Promise<Response>;
222

223
/** Promise wrapper for Linear API responses */
224
type LinearFetch<Response> = Promise<Response>;
225

226
/** Raw response from the Linear GraphQL API */
227
interface LinearRawResponse<Data> {
228
  /** The returned data */
229
  data?: Data;
230
  /** Any extensions returned by the Linear API */
231
  extensions?: unknown;
232
  /** Response headers */
233
  headers?: Headers;
234
  /** Response status */
235
  status?: number;
236
  /** An error message */
237
  error?: string;
238
  /** Any GraphQL errors returned by the Linear API */
239
  errors?: LinearGraphQLErrorRaw[];
240
}
241

242
/** Description of a GraphQL request used in error handling */
243
interface GraphQLRequestContext<Variables extends Record<string, unknown>> {
244
  query: string;
245
  variables?: Variables;
246
}
247
```