Reference > SDK > CMS
CMS
CmsSdk class for querying and mutating Headless CMS entries from external applications
- How to query entries from the Headless CMS using
sdk.cms? - How to create, update, publish, and delete CMS entries?
- How to use TypeScript generics for type-safe entry data?
- How to handle the Result pattern in CMS operations?
Overview
The CmsSdk class provides methods for interacting with Headless CMS entries from external applications. Access it via sdk.cms on a Webiny instance. All read operations use the Read API by default (published content only), while write operations use the Manage API. Methods return Result objects—check for success with isOk() before accessing values.
Read Methods
getEntry— fetch a single entry by ID or filterlistEntries— list entries with filtering, sorting, and pagination
Write Methods
createEntry— create a draft entryupdateEntryRevision— update specific fields on a revisionpublishEntryRevision— publish a revision to the Read APIunpublishEntryRevision— revert a revision to draftdeleteEntryRevision— delete a revision
CmsSdk
The CmsSdk class is instantiated automatically when you create a Webiny instance. Access it via the cms property.
getEntry
Retrieves a single entry from the CMS by ID, entry ID, or custom field values.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
params | GetEntryParams | Yes | Parameters for retrieving the entry |
params.modelId | string | Yes | The model ID of the entry to retrieve |
params.where | GetEntryWhere | Yes | Filter conditions for finding the entry |
params.where.id | string | No | The revision ID (e.g., "abc123#0001") |
params.where.entryId | string | No | The entry ID (e.g., "abc123") |
params.where.values | Record<string, unknown> | No | Filter by entry field values |
params.fields | string[] | Yes | Fields to include in response. Use "values.fieldId" for entry values or top-level fields like "id", "createdOn" |
params.preview | boolean | No | When true, uses Preview API to access unpublished/draft content. When false (default), uses Read API for published content only |
Return Type
Result<CmsEntryData<TValues>, HttpError | GraphQLError | NetworkError>
Returns a Result containing the entry data on success or an error on failure.
Example
listEntries
Lists entries from the CMS with support for filtering, sorting, pagination, and full-text search.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
params | ListEntriesParams | Yes | Parameters for listing entries |
params.modelId | string | Yes | The model ID of entries to list |
params.where | Record<string, unknown> | No | Filter conditions using operators like _eq, _gt, _contains, etc. |
params.sort | Record<string, "asc" \| "desc"> | No | Sort configuration (e.g., { "values.name": "asc" }) |
params.limit | number | No | Maximum number of entries to return (default: 10) |
params.after | string | No | Cursor for pagination from previous response |
params.search | string | No | Full-text search term to filter entries across searchable fields (text, longText fields with fullTextSearch enabled) |
params.fields | string[] | Yes | Fields to include in response. Use "values.fieldId" for entry values or top-level fields like "id", "createdOn" |
params.preview | boolean | No | When true, uses Preview API to access unpublished/draft content. When false (default), uses Read API for published content only |
Return Type
Result<ListEntriesResult<TValues>, HttpError | GraphQLError | NetworkError>
Returns a Result containing an object with:
data: Array ofCmsEntryData<TValues>objectsmeta: Pagination metadata (cursor,hasMoreItems,totalCount)
Example
createEntry
Creates a new entry in the CMS. The entry is created in draft status—call publishEntryRevision to make it publicly visible.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
params | CreateEntryParams<TValues> | Yes | Parameters for creating the entry |
params.modelId | string | Yes | The model ID for the entry |
params.data | CreateCmsEntryData<TValues> | Yes | The entry data to create. Must include values object with field data |
params.fields | string[] | Yes | Fields to include in response. Use "values.fieldId" for entry values or top-level fields like "id", "createdOn" |
Return Type
Result<CreateCmsEntryData<TValues>, HttpError | GraphQLError | NetworkError>
Returns a Result containing the created entry data on success or an error on failure.
Example
updateEntryRevision
Updates an existing entry revision in the CMS. Only the specified fields in data.values are modified—other fields remain unchanged.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
params | UpdateEntryRevisionParams<TValues> | Yes | Parameters for updating the entry revision |
params.modelId | string | Yes | The model ID for the entry |
params.revisionId | string | Yes | The revision ID of the entry to update (e.g., "abc123#0001") |
params.data | UpdateCmsEntryData<TValues> | Yes | The updated entry data. Use values for field updates |
params.fields | string[] | Yes | Fields to include in response. Use "values.fieldId" for entry values or top-level fields like "id", "createdOn" |
Return Type
Result<UpdateCmsEntryData<TValues>, HttpError | GraphQLError | NetworkError>
Returns a Result containing the updated entry data on success or an error on failure.
Example
publishEntryRevision
Publishes an entry revision, making it available via the Read API. Published entries are visible to public consumers of your content.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
params | PublishEntryRevisionParams | Yes | Parameters for publishing the entry revision |
params.modelId | string | Yes | The model ID of the entry to publish |
params.revisionId | string | Yes | The revision ID of the entry to publish (e.g., "abc123#0001") |
params.fields | string[] | Yes | Fields to include in response. Use "values.fieldId" for entry values or top-level fields like "id", "createdOn" |
Return Type
Result<CmsEntryData<TValues>, HttpError | GraphQLError | NetworkError>
Returns a Result containing the published entry data on success or an error on failure.
Example
unpublishEntryRevision
Unpublishes an entry revision, reverting it to draft status and removing it from the Read API.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
params | UnpublishEntryRevisionParams | Yes | Parameters for unpublishing the entry revision |
params.modelId | string | Yes | The model ID of the entry to unpublish |
params.revisionId | string | Yes | The revision ID of the entry to unpublish (e.g., "abc123#0001") |
params.fields | string[] | Yes | Fields to include in response. Use "values.fieldId" for entry values or top-level fields like "id", "createdOn" |
Return Type
Result<CmsEntryData<TValues>, HttpError | GraphQLError | NetworkError>
Returns a Result containing the unpublished entry data on success or an error on failure.
Example
deleteEntryRevision
Deletes an entry revision from the CMS. By default, performs a soft delete (entry can be restored). Pass permanent: true for permanent deletion.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
params | DeleteEntryRevisionParams | Yes | Parameters for deleting the entry revision |
params.modelId | string | Yes | The model ID of the entry to delete |
params.revisionId | string | Yes | The revision ID of the entry to delete (e.g., "abc123#0001") |
params.permanent | boolean | No | Whether to permanently delete the entry (default: false) |
Return Type
Result<boolean, HttpError | GraphQLError | NetworkError>
Returns a Result containing true on success or an error on failure.
Example
Types
CmsEntryValues
Base type for entry field values. Extend this interface to define your content model structure.
CmsEntryData
Type representing a complete CMS entry with metadata and field values.
CmsEntryStatus
Entry publication status.
CmsIdentity
User identity information in entry metadata.
Practical Examples
List With Filter, Sort, and Pagination
Get Entry by ID
Create and Publish Flow
TypeScript Generics Usage
Error Handling Pattern