Linear is the easiest provider in the network to overlook because the API count looks small: 2 APIs. But the shape of those two APIs is unusual enough — and influential enough on the modern dev-tool category — that it’s worth a closer look. One is a GraphQL API. The other is an AsyncAPI-documented webhook stream. That combination is rare in the catalog, and it’s what most new dev-tool providers will look like in 2027.
What’s in the surface
The two APIs in the Linear profile:
- Linear GraphQL API — the same API Linear’s own product uses. There is no separate REST surface for partners; the public GraphQL endpoint is the surface. Issues, projects, cycles, roadmaps, teams, attachments, comments — everything reachable from the UI is reachable from the API, and the schema is published as an OpenAPI document for catalog ingestion.
- Linear Webhooks API — push notifications when data is created, updated, or removed. Organization-scoped or team-scoped. Documented as AsyncAPI, not as REST docs that gesture at “here’s what we’ll POST you.” That’s the meaningful detail.
Two specs, two schemas, two distinct workflows. One for pull (query the API), one for push (subscribe to events). The clean separation between a synchronous query API and an event-driven webhook API — each with its own machine-readable contract — is exactly the shape an apis.io catalog wants to ingest, and exactly the shape downstream agents want to consume.
Why GraphQL-first matters for catalogs
When a provider ships GraphQL as the primary surface, the OpenAPI representation in the catalog is a translation, not the source of truth. That’s a real trade-off:
- You lose some of the per-operation granularity that REST gives you. There’s one POST endpoint and the world inside it is the schema.
- You gain a single contract that captures the full data model. Querying for “all issues with this label in this cycle assigned to this user” is one operation in GraphQL and would be a deeply-nested REST query in any other surface.
For agent consumption specifically, GraphQL is interesting because the agent can ask for exactly the shape it needs. No over-fetching, no nested pagination loops, no joining across endpoints. The downside — every agent needs to actually know how to construct a GraphQL query — is being eroded as model-generated GraphQL gets reliably good.
Why AsyncAPI on webhooks matters
Most providers in the catalog describe their webhooks in prose: “When X happens, we’ll POST you a payload that looks like {…}.” Linear ships an AsyncAPI document instead. That means:
- The event catalog is machine-readable. An agent or integration tool can enumerate the event types without scraping docs.
- The payload schemas are typed. Verification, deduplication, replay tooling can be generated rather than hand-coded.
- The catalog can ingest the webhook surface as a first-class API entity, with its own capabilities, its own asyncapi.apis.io listing, and its own discoverability.
This is the pattern apis.io has been arguing for since the AsyncAPI project matured. Linear is one of the providers that actually does it.
The takeaway
The Linear profile is small in API count and large in design implication. GraphQL as the primary query API, AsyncAPI as the primary event documentation, both shipped as parseable specs. The whole surface is two files, and those two files contain everything a downstream tool — agent or human — needs to build against.
If you’re shipping a new SaaS API in 2026 and wondering what the modern catalog-friendly shape is, providers.apis.io/providers/linear is the cleanest 2-file answer in the network. Two specs, two surfaces, complete coverage.