GraphQL Endpoint with Schema Introspection So Agents Can Learn Your Data Model
Lets AI agents query a single endpoint, discover the schema themselves, and build the right requests.
What this signal tests
We check whether your site exposes a GraphQL endpoint at a conventional path - /graphql, /api/graphql, or /v1/graphql - and whether that endpoint answers GraphQL's built-in introspection query. Introspection is GraphQL's standard mechanism for asking an endpoint to describe its own queries, mutations, and types in a machine-readable form.
Why it matters for your visibility in AI
If your team has invested in GraphQL, you already have most of what an agent needs. Where REST agents have to read a separate OpenAPI document and hope it matches the live API, a GraphQL agent can ask the endpoint directly what queries and mutations are available, what arguments each takes, and what the response shape will be. That self-description is unique to GraphQL and is exactly what AI agent frameworks were designed around. The consequence of disabling introspection in production - a common defensive default - is that agents see your endpoint as a black box and cannot use it without out-of-band documentation. The right answer is usually to leave introspection enabled and rely on auth, rate limits, and field-level authorisation for security. That way, your existing GraphQL surface becomes immediately agent-callable with zero new infrastructure.
Pass criteria at a glance
| Criterion | Passes when |
|---|---|
| GraphQL endpoint exists AND introspection returns schema (or static SDL at /graphql/schema.graphql). |
How we test it
Our scanner posts a small introspection query - asking for the queryType's name - to each conventional GraphQL path with Content-Type application/json. If any endpoint responds with HTTP 200 and a valid GraphQL data payload containing __schema.queryType.name, the test passes. If introspection is disabled, we also accept a static schema definition file (SDL) published at /graphql/schema.graphql.
Show technical detection method
POST {"query":"{__schema{queryType{name}}}"} with application/json; pass if 200 with data.__schema.queryType.name.
If your site fails: how to fix it
- Confirm with your engineering team whether introspection is currently disabled in production; many teams turned it off years ago as a precautionary default and never revisited the decision.
- Re-enable introspection in production, relying on authentication, rate limiting, and field-level authorization for real security; the GraphQL community now considers this the right default for agent-facing APIs.
- If your security posture genuinely requires introspection to remain off, publish a static SDL file at /graphql/schema.graphql and reference it via a Link header with rel=describedby on the GraphQL endpoint.
- Verify the endpoint responds at one of the conventional paths (/graphql, /api/graphql, or /v1/graphql); rename it if it lives somewhere unusual, because agents probe the conventional paths first.
- Keep the schema in sync with deployed resolvers via automated tests; agents will follow the schema literally and will fail loudly if a documented field returns errors.
Quick facts
| Maturity | ESTABLISHED |
|---|---|
| Weight | medium |
| Category | Agent Actions |
Primary sources
Related signals
Frequently asked questions
Is leaving introspection on a security risk?
It exposes the shape of your API, which is the same surface attackers can map manually with effort. Real protection comes from auth, rate limiting, and field-level authorization. Most major GraphQL deployments - GitHub, Shopify, Contentful - leave introspection on in production and rely on those layers.
What if we use persisted queries?
Persisted queries are a defence-in-depth pattern, not a substitute for introspection. You can keep persisted queries for your own clients while still allowing introspection so agents can learn the schema. The two patterns coexist comfortably in production.
How is this different from publishing OpenAPI?
OpenAPI describes REST APIs; introspection describes GraphQL APIs. If your API is GraphQL, introspection is the equivalent capability and agents expect it on the GraphQL endpoint. If your API has both REST and GraphQL surfaces, you should publish both OpenAPI and enable introspection.
Does this cost anything to implement?
Re-enabling introspection is a configuration change in your GraphQL server, usually one line. There are no licensing fees. Publishing a static SDL is a build-pipeline change, typically under an hour of developer time.
Run your own scan
Run a free scan and see how your site grades across all 155 AI-readiness signals.