> ## Documentation Index > Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt > Use this file to discover all available pages before exploring further. # Linear > Read and file issues, comments, teams, projects and users.
128 tools API key
```python linear_example.py {7} theme={null} import os from charter.packs import linear linear.configure(api_key=os.environ["LINEAR_API_KEY"]) issues = await linear.issues_list.ainvoke(variables={"first": 50}) ``` Issues and their relations, comments and reactions, labels, teams, members, workflow states, projects with their milestones and status updates, cycles, initiatives, documents, attachments, customers, notifications, favorites, saved views, search and webhooks. Every tool POSTs the same document-shaped request to the same URL, and the argument the model fills in is always one field: `variables`. A GraphQL API breaks three assumptions a REST-shaped runtime makes, and this pack is where each one is answered. ## Authenticating This pack takes an API key in `Authorization`, and [`configure()`](/charter/charter/reference/configuration#configure) is optional when `$LINEAR_API_KEY` is set. There is no authorization server, no consent screen and no refresh — [API keys](/charter/charter/auth/api-key-tool-factory) is the whole story. The key goes out **raw** — not `Bearer`, not `Token`, just the key. This is the one place Linear differs from almost every other API here. An OAuth access token does take `Bearer`; for that, build the factory yourself with `oauth_tool_factory`, which adds the prefix. Linear documents where a personal key is created in [its authentication guide](https://linear.app/developers/graphql#authentication). ## The client [`api_key_tool_factory`](/charter/charter/reference/factories#api_key_tool_factory) is the whole client: a thin wrapper over `httpx` that attaches your key and these endpoint constants to each request. No vendor SDK enters your dependency tree.
```python Without the pack theme={null} import os from charter import Envelope, api_key_tool_factory api_key = os.environ["LINEAR_API_KEY"] linear_api_client = api_key_tool_factory( base_url="https://api.linear.app/", api_key_headers={"Authorization": api_key}, body_format="json", query_format="repeat", body_case="camel", query_case="snake", path_case="snake", envelope=Envelope( ok_field="data.*.success", errors_field="errors", ), ) # static_body is per tool, not per API: query differs across 128 # of 128 tools. ``` ```python With the pack theme={null} import os from charter.packs import linear linear.configure(api_key=os.environ["LINEAR_API_KEY"]) # The base URL, the casing, the envelope and the pagination are # already declared. 128 tools, ready to hand to a model: tools = linear.TOOLS ```
### Paging through a list A cursor belongs to the tool that returns it, so it is declared on that tool's builder call: ```python linear_pagination.py theme={null} teams_list = linear_api_client( name="teams_list", args_schema=TeamsListRequest, method="POST", url_template="graphql", pagination=Pagination( cursor_field="pageInfo.endCursor", cursor_param="variables.after", more_field="pageInfo.hasNextPage", ), ) ``` Pagination is declared on `teams_list`, `users_list`, `workflow_states_list`, `team_memberships_list`, `issues_list`, `issue_relations_list`, `comments_list`, `issue_labels_list`, `project_labels_list`, `projects_list`, `project_statuses_list`, `project_milestones_list`, `project_updates_list`, `cycles_list`, `initiatives_list`, `initiative_updates_list`, `documents_list`, `attachments_list`, `attachments_for_url`, `customers_list`, `customer_needs_list`, `customer_statuses_list`, `customer_tiers_list`, `notifications_list`, `favorites_list`, `custom_views_list`, `search_issues`, `search_projects`, `search_documents` and `webhooks_list`. The other 98 take no cursor. ## Tools Each is a [`Tool`](/charter/charter/reference/tool), called with [`ainvoke`](/charter/charter/reference/tool#tool-ainvoke) as in the snippet above. The name links to its parameters, its response and what it costs.
Workspace viewerPOST Get the authenticated Linear user. organizationPOST Get the workspace itself — its name, URL key and member count. teams\_listPOST List the workspace's teams. team\_getPOST Get one team, with its workflow states and current cycle. users\_listPOST List workspace members. user\_getPOST Get one workspace member. workflow\_states\_listPOST List workflow states — the statuses an issue can move between. workflow\_state\_getPOST Get one workflow state by its UUID. workflow\_state\_createPOST Create a workflow state for a team. workflow\_state\_updatePOST Rename a workflow state, recolour it or move its position. workflow\_state\_archivePOST Archive a workflow state, taking it out of the team's workflow. team\_memberships\_listPOST List who belongs to which team, and who owns each one. team\_membership\_getPOST Get one team membership by its UUID. team\_membership\_createPOST Add a member to a team. team\_membership\_updatePOST Change a team membership — chiefly to make someone the team's owner. team\_membership\_deletePOST Remove a member from a team. Issues issues\_listPOST List issues, optionally filtered. issue\_getPOST Get one issue with its description, comments, sub-issues, relations and attachments. issue\_createPOST Create an issue. issue\_updatePOST Update an issue. issue\_batch\_updatePOST Apply one change to many issues at once — reassigning a queue, moving a set into a cycle. issue\_deletePOST Move an issue to the trash, from where it can be restored. issue\_archivePOST Archive an issue, taking it out of the active lists while keeping it findable. issue\_unarchivePOST Restore an archived issue to the active lists. issue\_add\_labelPOST Add one label to an issue, leaving its other labels alone. issue\_remove\_labelPOST Remove one label from an issue, leaving its other labels alone. issue\_subscribePOST Subscribe someone to an issue's updates. issue\_unsubscribePOST Unsubscribe someone from an issue's updates. issue\_relations\_listPOST List the links between issues across the workspace. issue\_relation\_getPOST Get one issue relation by its UUID. issue\_relation\_createPOST Link two issues as blocking, duplicate, related or similar. 'blocks' and 'duplicate' are directional: the issue in issue\_id is the one doing the blocking, or the one that is the duplicate. issue\_relation\_updatePOST Change how two issues are linked, or which issues the link joins. issue\_relation\_deletePOST Unlink two issues. Comments comments\_listPOST Read comments. comment\_getPOST Get one comment with its replies. comment\_createPOST Post a comment. comment\_updatePOST Edit a comment's text, by its UUID. comment\_deletePOST Delete a comment. comment\_resolvePOST Mark a comment thread resolved. comment\_unresolvePOST Reopen a resolved comment thread. reaction\_createPOST React to a comment, issue or status update with an emoji. reaction\_deletePOST Remove a reaction. Labels issue\_labels\_listPOST List the workspace's issue labels, with the UUIDs issue\_create and issue\_update need. issue\_label\_getPOST Get one label by its UUID. issue\_label\_createPOST Create a label. issue\_label\_updatePOST Rename a label, recolour it, or retire it. issue\_label\_deletePOST Delete a label, removing it from every issue that carries it. project\_labels\_listPOST List the labels that tag projects. Projects projects\_listPOST List projects in the workspace, with their status and progress. project\_getPOST Get one project with its content, milestones and members. project\_createPOST Create a project. project\_updatePOST Update a project's name, description, lead, dates or status. project\_deletePOST Move a project to the trash. project\_unarchivePOST Restore a trashed project. project\_add\_labelPOST Add one project label to a project. project\_remove\_labelPOST Remove one project label from a project. project\_statuses\_listPOST List the statuses a project can be in, with the UUIDs project\_create and project\_update need. project\_milestones\_listPOST List project milestones. project\_milestone\_getPOST Get one project milestone by its UUID. project\_milestone\_createPOST Create a milestone inside a project. project\_milestone\_updatePOST Rename a milestone, move its target date, or move it to another project. project\_milestone\_deletePOST Delete a project milestone. project\_updates\_listPOST Read the status updates posted on projects — the periodic 'on track, here is what moved' notes. project\_update\_getPOST Get one project status update by its UUID. project\_update\_createPOST Post a status update on a project, optionally reporting health as 'onTrack', 'atRisk' or 'offTrack'. project\_update\_updatePOST Edit a project status update that has already been posted. project\_update\_archivePOST Archive a project status update. Cycles cycles\_listPOST List cycles — Linear's name for a team's time-box. cycle\_getPOST Get one cycle with the issues in it. cycle\_updatePOST Rename a cycle or move its dates. cycle\_archivePOST Archive a cycle. cycle\_start\_upcoming\_todayPOST Start a team's next cycle today rather than on its scheduled date. Initiatives initiatives\_listPOST List initiatives — the grouping above a project, and what Linear replaced roadmaps with. initiative\_getPOST Get one initiative with its projects and links. initiative\_createPOST Create an initiative. initiative\_updatePOST Update an initiative's name, owner, status or target date. initiative\_deletePOST Move an initiative to the trash. initiative\_archivePOST Archive an initiative. initiative\_unarchivePOST Restore an archived initiative. initiative\_to\_project\_createPOST Add a project to an initiative. initiative\_to\_project\_deletePOST Remove a project from an initiative. initiative\_updates\_listPOST Read the status updates posted on initiatives. initiative\_update\_createPOST Post a status update on an initiative. Documents documents\_listPOST List documents. document\_getPOST Get one document with its full content. document\_createPOST Create a document. document\_updatePOST Update a document. document\_deletePOST Move a document to the trash. document\_unarchivePOST Restore a trashed document. Attachments attachments\_listPOST List attachments — the links between Linear issues and things outside it. attachment\_getPOST Get one attachment and the issue it is on. attachments\_for\_urlPOST Find which issues an external URL is attached to. attachment\_createPOST Link an issue to something outside Linear. attachment\_updatePOST Update an attachment's title, subtitle or icon. attachment\_deletePOST Remove an attachment from its issue. Customers customers\_listPOST List customers — the companies whose requests Linear tracks against issues. customer\_getPOST Get one customer by its UUID. customer\_createPOST Create a customer. customer\_updatePOST Update a customer's name, owner, tier, revenue or size. customer\_deletePOST Delete a customer. customer\_needs\_listPOST List customer requests. customer\_need\_createPOST Record a customer request, optionally attached to an issue or project. customer\_need\_updatePOST Update a customer request, chiefly to attach it to an issue. customer\_need\_deletePOST Delete a customer request. customer\_statuses\_listPOST List the statuses a customer can be in, with the UUIDs customer writes need. customer\_tiers\_listPOST List the tiers a customer can be assigned to. Inbox notifications\_listPOST Read the authenticated user's notifications — what Linear has told them about and what is still unread. notification\_getPOST Get one notification by its UUID. notification\_updatePOST Mark a notification read by setting read\_at, or snooze it with snoozed\_until\_at. notification\_archivePOST Archive a notification. notification\_unarchivePOST Restore an archived notification. notification\_mark\_read\_allPOST Mark every notification raised by one issue, project or initiative as read. favorites\_listPOST List what the authenticated user has starred. favorite\_createPOST Star an issue, project, document, view, label, team or user. favorite\_updatePOST Move a favorite into a folder, or reorder it. favorite\_deletePOST Unstar something. custom\_views\_listPOST List the workspace's saved views, each with the filter it holds. custom\_view\_getPOST Get one saved view. custom\_view\_createPOST Save a filter as a view. custom\_view\_deletePOST Delete a saved view. Search search\_issuesPOST Search issues by text, across titles and descriptions. search\_projectsPOST Search projects by text, across names and descriptions. search\_documentsPOST Search documents by text, across titles and content. Webhooks webhooks\_listPOST List the workspace's webhooks. webhook\_getPOST Get one webhook by its UUID. webhook\_createPOST Create a webhook. webhook\_updatePOST Update a webhook's URL, resource types, secret, or whether it is enabled. webhook\_deletePOST Delete a webhook.
A hundred and twenty-eight identical rows in the Path column is not a rendering bug. It is the shape of the API. ## The document is a constant, not a parameter What distinguishes `issues_list` from `issue_create` is the query document, which belongs to the tool rather than to the call. It goes on the wire through `static_body`: ```python linear_declare_issues_list.py theme={null} issues_list = linear( name="issues_list", args_schema=IssuesListRequest, # one `variables` field, Body(envelop=True) method="POST", url_template="graphql", static_body={"query": ISSUES_DOCUMENT}, ) ``` `static_body` keys are sent verbatim, are not case-converted, and never appear in the LLM schema — so the document costs nothing in context and a model cannot see or rewrite it. Static values are applied last, so a schema field named `query` would lose to the document rather than overwrite it. That is the whole boundary. A GraphQL endpoint accepts arbitrary documents, so a tool that let the model supply one would not be an integration, it would be a shell. The documents live in `charter.packs.linear.queries`. ## Failure arrives as HTTP 200, twice over GraphQL puts document-level problems in an `errors` array beside the data. But a *mutation* Linear understood and then declined comes back with no `errors` at all, and the refusal one level below the operation name: ```json linear_failure_200.json theme={null} {"data": {"issueCreate": {"success": false, "issue": null}}} ``` Every signal a runtime normally trusts says the write happened. So the envelope's field names are paths, and `*` stands for whichever operation the tool called: ```python linear_envelope.py theme={null} from charter import Envelope Envelope(errors_field="errors", ok_field="data.*.success") ``` One declaration covers both places, every mutation in the pack, and any mutation added later by someone who never read the source. A query has no `success` anywhere, and a wildcard that matches nothing is not a failure, so queries pass through untouched. See [envelopes](/charter/charter/tools/envelopes) for why this is a declaration rather than a check inside each mutation's response handler. ## A cursor that goes out nested Linear pages Relay-style: the cursor comes back at `pageInfo.endCursor` and goes out at `variables.after` — *inside* the variables object, not beside it. `cursor_param` takes a dotted path for exactly this. ```python linear_page_through_issues.py theme={null} args = {"variables": {"first": 50}} while args is not None: page = await linear.issues_list.ainvoke(args) handle(page) args = linear.issues_list.pagination.next_page_args(page, args) ``` `pageInfo.hasNextPage` is declared because Linear keeps sending an `endCursor` on the last page — without it the walk never terminates. The paths are read against the *trimmed* payload: every tool runs an `unwrap` handler that strips `data` and the operation name first, which is why `pageInfo` sits at the root here rather than three levels down. ## Gotchas `issue_create` wants a `team_id`, not `"ENG"`; `assignee_id`, not a person's name; `state_id`, not `"Done"`. Resolve them first with `teams_list`, `users_list` and `workflow_states_list`. Workflow states are per-team, so filter by team when resolving one. Closing an issue is `issue_update` with a `state_id` whose type is `completed` or `canceled`. `workflow_states_list` returns each state's `type`, which is how you find the right id without hard-coding it. `issue_update` takes both. `label_ids` overwrites the issue's labels outright, the way GitHub's `issues_update` behaves. `added_label_ids` and `removed_label_ids` adjust the set that is already there, so the read-modify-write round trip is not needed — and neither is `issue_add_label`, which does the same thing for a single label. `body_case="camel"`, so `team_id` in your arguments arrives as `teamId` in the GraphQL variables. That is the [cascade](/charter/charter/tools/key-case-cascade) doing its job; it is called out here because GraphQL's convention happens to match Charter's default and it is easy to assume nothing is happening. Linear's `IssueFilter` is recursive. Conditions on one filter object combine with AND; `and_` and `or_` each take a list of filters and nest arbitrarily deep, which is how "urgent **or** assigned to me" is written. The trailing underscores are there because `and` and `or` are Python keywords — the casing layer strips them on the way to the wire, exactly as it does for `in_`. What is modelled is the issue's own columns and its relationships one level deep. Linear's own type also carries comparators for source metadata, agent-session existence, SLA timings and suggestion collections; those describe Linear's internals rather than the work, and are absent. The mutation `projectUpdate` edits a **project**. The resource `ProjectUpdate` is a **status post** written on one, with its own `projectUpdateCreate` and `projectUpdates` connection. The tools mirror Linear's names rather than inventing clearer ones, so each can be checked against the documentation it came from: `project_update` edits a project, and `project_update_create`, `project_update_update`, `project_update_get` and `project_updates_list` work on status posts. `project_create` and `project_update` take a `status_id` that comes from `project_statuses_list`. There is no `state` field on either input, and a pack that offered one sent a field Linear rejects. Setting the status is also how a project is completed or cancelled — there is no separate operation, the same way there is none for closing an issue. `issue_delete`, `project_delete` and `document_delete` move the thing to the trash and answer with it, so it can be restored. Only `issue_delete`'s `permanently_delete` erases, and it is never sent unless asked for. `comment_delete`, `webhook_delete` and the rest are true deletes, and answer with the id they removed and nothing else. Each tool asks for the fields in its document and no others. That is deliberate: it is what makes the response shape a property of the pack source rather than of the call, and it is what keeps Linear's complexity budget predictable. ## Related * [Envelopes](/charter/charter/tools/envelopes) — paths, wildcards, and failure below the root * [The wire contract](/charter/charter/tools/wire-contract) — `static_body` and nested cursor parameters * [Shopify](/charter/charter/packs/shopify) — the other GraphQL pack, and what it breaks that this one does not