Using the Webiny SDK

Overview

This guide covers practical examples of working with Headless CMS content using the Webiny SDK. The SDK is the recommended way to interact with a Webiny instance from external JavaScript or TypeScript applications such as Next.js, Vue, SvelteKit, or Node.js scripts. It provides type-safe methods for querying and mutating content, with automatic API selection and built-in error handling.

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

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

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

Working With Reference Fields

To retrieve data from a referenced entry, include the nested field paths in fields. Reference field values are accessed via values.{referenceField}.values.{nestedField}:

Mutating Entries

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

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)