# API GraphQL Persisted Queries and Operation Safelists
Status: public
Confidence: medium (0.685) (verified)
Last verified: 2026-06-03
Generation: ai_structured


## TL;DR

GraphQL persisted queries and operation safelists help agents distinguish approved operations from arbitrary query text and avoid relying on ad hoc introspection.

## Core Explanation

Persisted query systems replace or constrain full GraphQL operation text with registered IDs or hashes. For agents, this creates a safer lookup surface: the agent can inspect approved operations, expected variables, client manifests, and rejected-operation logs.

Agents should verify whether the system uses APQ caching, a persisted query list, safelisting, or ID-only safelisting. These modes have different failure cases and rollout risks.

## Source-Mapped Facts

- Apollo GraphOS documentation says APQ does not provide safelisting because the router dynamically populates its APQ cache with operations it receives. ([source](https://www.apollographql.com/docs/graphos/platform/security/persisted-queries))
- Apollo GraphOS documentation says persisted-query safelisting can restrict execution to operations present in a persisted query list. ([source](https://www.apollographql.com/docs/graphos/platform/security/persisted-queries))
- Apollo Client documentation says its persisted queries link requires a SHA-256 hash function. ([source](https://www.apollographql.com/docs/react/data/persisted-queries))

## Further Reading

- [Apollo GraphOS Safelisting with Persisted Queries](https://www.apollographql.com/docs/graphos/platform/security/persisted-queries)
- [Apollo Client Persisted Queries](https://www.apollographql.com/docs/react/data/persisted-queries)