Mastering the Contentstack Delivery API and GraphQL

The Delivery API is the read-only gateway to your published content

Once content is modeled and published, your frontend reads it through the Content Delivery API (CDA) — a fast, read-only, CDN-backed API. This guide covers querying it well, including references and GraphQL.

Delivery vs. Management Tokens

Two very different keys:

Token Access Where it belongs
Delivery token Read-only, per environment Safe in frontend
Management token Read/write Server-side only — never ship it

Querying with the SDK

import Contentstack from 'contentstack';
const Stack = Contentstack.Stack({
  api_key: 'API_KEY', delivery_token: 'TOKEN', environment: 'production',
});
const q = Stack.ContentType('article').Query();
const [entries] = await q.where('category', 'guides')
  .includeReference('author').limit(10).toJSON().find();

Resolving references in one request avoids waterfall fetches

Resolving References

By default references return only a UID. Use includeReference to pull the linked entry inline — fetch an article and its author in a single round trip instead of two.

REST vs. GraphQL

  • REST/SDK — simplest for straightforward queries and filtering
  • GraphQL — fetch exactly the fields you need, resolve deep references in one query, ideal for complex pages

Performance Habits

  1. Request only needed fields (only/GraphQL selection sets).
  2. Cache responses — the CDA is CDN-backed; pair it with your framework’s caching.
  3. Paginate large collections with limit and skip.

Treat the Delivery API as a CDN: cache aggressively and invalidate on publish via webhooks.

What to Learn Next

  • Webhooks to revalidate caches on publish
  • Image Delivery API for on-the-fly transformations
  • Live Preview API for editor previews

Arivanandhan Chitheshwaran