Using the GraphQL API

Overview

This guide covers practical examples of working with Headless CMS content using the Webiny SDK. The SDK provides type-safe methods for querying and mutating content, with automatic API selection and built-in error handling.

For an explanation of the Read and Manage APIs, see GraphQL API Overview.

Prerequisites

• Webiny SDK initialized in your project
• API key with appropriate permissions (read-only or full-access)
• At least one content model created in Headless CMS

Defining TypeScript Types

Define interfaces that match your content model structure. Field names must match the field IDs (not labels) from your content model:

Key points:

• Field names match field IDs from content model
• Reference fields use CmsEntryData<T> type
• Optional fields use ? suffix

Querying Entries

List All Entries

Sorting Results

Sort options:

• values.{fieldId}_ASC - Ascending order
• values.{fieldId}_DESC - Descending order
• createdOn_ASC / createdOn_DESC - Sort by creation date
• savedOn_ASC / savedOn_DESC - Sort by last saved date

Filtering Results

Common filter operators:

• _eq - Equals
• _ne - Not equals
• _in - In array
• _not_in - Not in array
• _lt - Less than
• _lte - Less than or equal
• _gt - Greater than
• _gte - Greater than or equal
• _contains - Contains substring
• _not_contains - Does not contain substring

Pagination

Get Single Entry

Creating Entries

Important:

• createEntry() uses the Manage API
• Entry is created in draft status
• Call publishEntry() to make it publicly visible

Updating Entries

Note: updateEntry() only modifies the specified fields. Other fields remain unchanged.

Publishing Entries

Publishing makes an entry available via the Read API. Unpublished (draft) entries are only accessible via the Manage API.

Deleting Entries

Warning: Deletion is permanent and cannot be undone.

Error Handling

All SDK methods return a Result type. Always check for errors before accessing the value:

Common error scenarios:

• Entry not found (entryId does not exist)
• Permission denied (API key lacks permissions)
• Validation errors (required fields missing)
• Network errors (API unreachable)

Working With Reference Fields

When a field references another model, the SDK returns the full referenced entry:

Reference field structure:

Server Components vs Client Components

Server Components (recommended for queries):

Server Actions (for mutations):

Entry Structure

Every entry returned by the SDK has this structure:

Type Safety

Pass your interface as a generic to SDK methods for full type safety: