# Linear docs: AI Agent Readiness Score 68.8% (D+)

**68.8% · 55/80 · AI Agent Readiness Score · 25/30 reading points · 30/50 agent surface points**

Linear received 10 PASS votes and passed 3 of five agent surface checks. The clearest finding came from the recover from a RATELIMITED error task.

- Tested: 2026-09-22
- Published: 2026-09-22
- Battery: v1
- Scoring: reading 30 pts · surface 50 pts
- Docs: https://linear.app/developers

Three AI models, GPT 5.6 Sol, Claude Opus 5, and DeepSeek v4 Flash, each read Linear’s public documentation independently and attempted five first-hour developer jobs: run the first GraphQL call, find the exact limits, recover from a RATELIMITED error, verify a webhook, use the TypeScript SDK.

No accounts, API calls, or code execution were used. Every verdict came from public pages and every published quotation passed a live verification check. Preflight substitutions: T3: Linear answers a rate-limited GraphQL request with HTTP 400 and a RATELIMITED error code in the errors array rather than HTTP 429, so that documented error replaces 429.

## Freshness

[How rechecks work](https://docsforagents.com/methodology/#freshness)

- Category: [Productivity & collaboration](https://docsforagents.com/grades/?category=productivity)
- Tested: 2026-09-22
- Quotes verified: 2026-09-22
- Surface rechecked: Not yet rechecked

## Agent surface checks · 30/50

| Check | Verdict | Points |
| --- | --- | --- |
| llms.txt | PASS | 10 |
| llms-full.txt | FAIL | 0 |
| Markdown mirror | PASS | 10 |
| MCP server | PASS | 10 |
| Docs AI | FAIL | 0 |

## The Reading Test · 25/30

| Task | GPT 5.6 Sol | Opus 5 | DeepSeek v4F | Consensus |
| --- | --- | --- | --- | --- |
| Run the first GraphQL call | PASS | PASS | PASS | PASS |
| Find the exact limits | PASS | PASS | PASS | PASS |
| Recover from a RATELIMITED error | PARTIAL | PARTIAL | PARTIAL | PARTIAL |
| Verify a webhook | PASS | PASS | PASS | PASS |
| Use the TypeScript SDK | PASS | PARTIAL | PARTIAL | PARTIAL |

Docs platform: Custom Next.js (unscored) · verified 2026-09-22

## What to fix first

These 4 fixes could add up to 25 points to the AI Agent Readiness Score. The list ranks each fix by the points it would add. [How the ranking works](https://docsforagents.com/methodology/#what-to-fix-first)

1. **+10 points · llms-full.txt · check failed**

   **Found:** HTTP 200 but content-type text/html serving the Linear application shell rather than documentation text.

   **Fix:** Publish llms-full.txt at the docs root with the full text of every docs page in one plain-text file.

   **Evidence:** [linear.app/llms-full.txt](https://linear.app/llms-full.txt)

2. **+10 points · Docs AI · check failed**

   **Found:** The hydrated developer docs offer only a Search control, and no assistant control or assistant provider script loads.

   **Fix:** Add an assistant to the docs site that answers questions from the docs and links to its sources.

3. **+3 points · Recover from a RATELIMITED error · PARTIAL**

   **Found:** The rate-limiting page names the RATELIMITED code but no field tells a request limit from a complexity limit, and no page states a retry procedure.

   **Fix:** On the rate-limiting page, show the full RATELIMITED error body, say which X-RateLimit header identifies the limit that fired, and give the wait-then-retry steps.

   **Evidence:** [linear.app/developers/rate-limiting](https://linear.app/developers/rate-limiting)

4. **+2 points · Use the TypeScript SDK · PARTIAL**

   **Found:** The SDK page calls the operation createIssue while the API docs call it issueCreate, and the create example uses a linearClient the getting-started steps never define.

   **Fix:** Document that the SDK method createIssue maps to the issueCreate mutation, and show the create example with the same client variable the getting-started steps build.

   **Evidence:** [linear.app/developers/sdk-fetching-and-modifying-data](https://linear.app/developers/sdk-fetching-and-modifying-data)

## What the docs get right

- **Run the first GraphQL call: 3 PASS votes.** The GraphQL page links to key creation and provides the required header, endpoint, and a complete curl query.
- **Find the exact limits: 3 PASS votes.** The page lists 2,500, 5,000, and 600 requests plus 3,000,000, 2,000,000, and 100,000 points per hour for API key, OAuth app, and unauthenticated traffic.
- **3 of 5 agent surface checks.** Present: llms.txt, markdown mirrors, an MCP server. Missing: llms-full.txt, docs AI.

## Run the first GraphQL call

**PASS**

PASS consensus from 3 PASS.

The GraphQL page links to key creation and provides the required header, endpoint, and a complete curl query. One page carries the endpoint, a linked route to Security & access settings for key creation, the exact header form without a Bearer prefix, and a runnable curl example. One clear path: create a personal API key at Settings → Security & access, then POST to https://api.linear.app/graphql with the Authorization header and a sample query in the request body.

## Find the exact limits

**PASS**

PASS consensus from 3 PASS.

The page lists 2,500, 5,000, and 600 requests plus 3,000,000, 2,000,000, and 100,000 points per hour for API key, OAuth app, and unauthenticated traffic. One page states every number for all three authentication types: 2,500 / 5,000 / 600 requests per hour and 3,000,000 / 2,000,000 / 100,000 complexity points per hour, plus a 10,000-point ceiling on any single query, and no other page restates them. All limits are exact numbers in tables: API key 2,500 requests/h + 3,000,000 complexity points/h, OAuth App 5,000 requests/h + 2,000,000 complexity points/h, unauthenticated 600 requests/h + 100,000 complexity points/h, plus max 10,000 complexity per query. Numbers are consistent across the single rate-limiting page.

## Recover from a RATELIMITED error

**PARTIAL**

PARTIAL consensus from 3 PARTIAL.

The page shows separate limit headers, but it does not map a generic error to one limiter or state a complete retry procedure. The status code and error code are exact, but the sample body elides both the message and the extensions fields as "...", no field distinguishes a request limit from a complexity limit from a per-endpoint limit, and no page gives retry or backoff guidance, so the correction has to be inferred from which X-RateLimit-*-Remaining header reached zero. The response shape (HTTP 400, RATELIMITED code in errors array) and rate-limit headers (Reset, Remaining, Limit) are documented, but no explicit recovery procedure says 'wait for the reset time then retry'. An agent must infer the correction path from descriptions of the leaky-bucket algorithm and the reset-time headers.

## Verify a webhook

**PASS**

PASS consensus from 3 PASS.

The page documents an HTTPS receiver, creation, a test trigger, delivery shape, raw-body HMAC-SHA256 and timestamp checks, and required status responses. The page covers the whole path in order: consumer requirements, creation through the UI and through the webhookCreate mutation, the full header list, the payload shape, and a complete Express verification example using timingSafeEqual plus a 60-second replay window. End-to-end path: create a webhook via API or settings, receive POST deliveries, verify HMAC-SHA256 signature against the signing secret, check the webhookTimestamp against system time to prevent replay attacks. Includes a complete Express.js code example.

## Use the TypeScript SDK

**PARTIAL**

PARTIAL consensus from 1 PASS, 2 PARTIAL.

The SDK pages install @linear/sdk, create a client, and call createIssue with teamId and title, matching the GraphQL issueCreate input fields. The input fields match the GraphQL docs, but the SDK names the operation createIssue while the API docs name it issueCreate and no page documents that inversion, and the create example sits on a different page from the SDK getting-started steps, which construct the client as client1 and client2 and then use an undefined linearClient. The SDK docs show installation (npm install @linear/sdk), client creation, and a query example, but do not show how to create an issue with the SDK. The createIssue example exists only in the SDK source code test files (readme.test.ts) and the generated SDK. The GraphQL API page documents the issueCreate mutation. An agent must cross-reference the GraphQL mutation page or examine the SDK source to find a minimum working example.

## The receipt

> With GraphQL requests, response http status code will be 400, but you can catch these by inspecting the errors in the response body containing the RATELIMITED error code.

The page shows separate limit headers, but it does not map a generic error to one limiter or state a complete retry procedure.

- [linear.app/developers/rate-limiting](https://linear.app/developers/rate-limiting)

## Agent surface notes

Initialize returned HTTP 401 with a Bearer OAuth challenge naming resource metadata at mcp.linear.app/.well-known/oauth-protected-resource/mcp.

The hydrated developer docs offer only a Search control, and no assistant control or assistant provider script loads.

## Method note

This is a reading test of public documentation, not an execution test. No accounts were created and no API calls were run. The AI Agent Readiness Score counts fifteen reading votes at PASS 2, PARTIAL 1, and FAIL 0, for 30 possible points. Five agent surface checks add 10 points each. The total is 80. Consensus chips show each row majority and do not affect scoring. The panel split on 1 of five tasks. Quotes shown here were re-fetched and confirmed verbatim on 2026-09-22.

Methodology: https://docsforagents.com/methodology/

Canonical URL: https://docsforagents.com/reports/linear-docs-ai-agent-readiness/