Querying

The list endpoints share a small set of query parameters. They behave the same way wherever they appear; the defaults differ slightly between endpoints, and those differences are called out below.

Pagination

Lists are paged with limit and offset:

curl "https://api.graphcms.io/v1/content/blog-posts?limit=20&offset=40" \
  -H "Authorization: Bearer $GRAPH_API_KEY"

• limit is clamped to between 1 and 100. A value that isn't a number falls back to the default: 10 for /v1/content/:type, 50 for /v1/content.
• offset can't go below 0.
• Entries are ordered newest first, by when they were created.

Every list response carries the totals you need to build pagination:

{ "pagination": { "limit": 20, "offset": 40, "total": 132 } }

A loop that reads every entry of a type:

1async function allEntries(type) {
2  const entries = [];
3  for (let offset = 0; ; offset += 100) {
4    const response = await fetch(
5      `https://api.graphcms.io/v1/content/${type}?limit=100&offset=${offset}`,
6      { headers: { Authorization: `Bearer ${process.env.GRAPH_API_KEY}` } }
7    );
8    const { data, pagination } = await response.json();
9    entries.push(...data);
10    if (offset + data.length >= pagination.total) return entries;
11  }
12}

Status

Entries are draft, published or archived.

Fetching drafts is how a preview mode works: render ?status=draft results behind your own preview check. For previewing whole sets of changes, staging is usually the better fit.

Language

Each entry is written in one language (default en-US). The language parameter filters by it:

curl "https://api.graphcms.io/v1/content/blog-posts?language=fr-FR" \
  -H "Authorization: Bearer $GRAPH_API_KEY"

On /v1/content/:type and /v1/content/:type/:slug it defaults to en-US, so entries written in another language only appear when you ask for that language. GraphQL doesn't filter by language unless you pass language.

Locale

locale is different from language: it doesn't filter anything. It picks which translation of an entry's text fields to return, falling back to the original where no translation exists.

curl "https://api.graphcms.io/v1/content/blog-posts?locale=de-DE" \
  -H "Authorization: Bearer $GRAPH_API_KEY"

The response's locale property says which locale was applied. An unsupported code is a 400. See Localization for the supported codes and how translations work.

Environment

Every endpoint takes environment=production (the default) or environment=staging, or the same value in an X-Environment header:

curl "https://api.graphcms.io/v1/content/blog-posts?environment=staging" \
  -H "Authorization: Bearer $GRAPH_API_KEY"

See Environments.

Combining parameters

Parameters combine freely:

curl "https://api.graphcms.io/v1/content/blog-posts?status=draft&locale=fr-FR&environment=staging&limit=5" \
  -H "Authorization: Bearer $GRAPH_API_KEY"

This returns up to five draft blog posts from staging, with their text fields in French where translated.