A Strong Performer in The Forrester Wave™: Digital Experience Platforms, Q4 2025
CS-log-dark.svg

Contentstack Delivery Ruby SDK

Ruby SDK for Contentstack's Content Delivery API

Contentstack is a headless CMS with an API-first approach. It is a CMS that developers can use to build powerful cross-platform applications in their favorite languages. Build your application frontend, and Contentstack will take care of the rest. Read More.

Prerequisites

You need ruby v2.0 or later installed to use the Contentstack Ruby SDK.

SDK installation and setup

Add the following code to your application's Gemfile and bundle:

gem 'contentstack'

Or you can run this command in your terminal (you might need administrator privileges to perform this installation):

gem install contentstack

Quickstart in 5 mins

Initialize SDK

You will need to specify the API key, Access token, and Environment Name of your stack to initialize the SDK:

@stack = Contentstack::Client.new("api_key", "delivery_token", "environment")

Once you have initialized the SDK, you can start getting content in your app
For Setting other regions:

Refer the below code if you want to use the Europe, Azure North America, Azure Europe, GCP North America, or GCP Europe region.

JavaScriptAndroidObjective-C.NetJavaPHPRubyPythonDartSwift

@stack = Contentstack::Client.new("api_key", "delivery_token", "environment",{"region": Contentstack::Region::<<add_your_region>>})

For Setting the Branch:

If you want to initialize SDK in a particular branch use the code given below:

@stack = Contentstack::Client.<span>new</span>("api_key", "delivery_token", "environment",{"branch": "branch"})

Note For Europe, set the region as EU, for Azure North America and Azure Europe, set the region as AZURE_NA and AZURE_EU respectively, for GCP North America set the region as GCP_NA, and for GCP Europe set the region as GCP_EU.

Basic Queries

Get a Single Entry

To retrieve a single entry from a content type, use the code snippet given below:

@stack = Contentstack::Client.new("api_key", "delivery_token", "environment")

@entries = @stack.content_type("content_type_uid").entry("entry_uid").fetch

Get Multiple Entries

To retrieve multiple entries of a particular content type, use the code snippet given below:

@stack = Contentstack::Client.new("api_key", "delivery_token", "environment")

@entries = @stack.content_type("content_type_uid").query.fetch

Note By default, the limit for response details per request is 100, with the maximum limit set at 250.

Paginating Responses

In a single instance, the Get Multiple Entries query will retrieve only the first 100 items of the specified content type. You can paginate and retrieve the rest of the items in batches using the skip and limit parameters in subsequent requests.

@stack = Contentstack::Client.new("api_key", "delivery_token", "environment")

@entries = @stack.content_type('category').query

           .limit(20)

           .skip(50)

           .fetch

Client

Initialize an instance of ‘Client’
NameTypeDescription
api_key (required)string
Stack API Key.
delivery_token (required)string
Stack Delivery token.
environment (required)string

Stack Environment name.

assets

Retrieves all assets of a stack by default.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@assets = @stack.assets.fetch;

asset

Retrieve a single asset with its UID.

NameTypeDescription
uidstring

The asset uid 

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@asset = @stack.asset("asset_uid").fetch;

content_types

This method returns comprehensive information of all the content types of a particular stack in your account.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@content_types = @stack.content_types;

content_type

Set the content type of which you want to retrieve the entries
NameTypeDescription
content_type_uidstring

UID of the existing content type

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@content_type = @stack.content_type("content_type_uid");

live_preview_query

For live preview data to be fetched provide query parameter to this function

NameTypeDescription
queryobject

Query parameter for live preview contents.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@stack.live_preview_query({

	"live_preview": "live_preview_hash",

	"content_type_uid": "content_type_uid",

	"entry_uid": "entry_uid"

});

sync

Syncs your Contentstack data with your app and ensures that the data is always up-to-date by providing delta updates
NameTypeDescription
param.initboolean
initializing sync
param.localestring
initializing sync with entries of a specific locale
param.start_datestringDefault: initializing sync with entries published after a specific date
param.content_type_uidstring

initializing sync with entries of a specific content type

param.typestring

Use the type parameter to get a specific type of content.Supports 'asset_published', 'entry_published', 'asset_unpublished', 'entry_unpublished', 'asset_deleted', 'entry_deleted', 'content_type_deleted'

param.pagination_tokenstring

Fetching the next batch of entries using pagination token

param.sync_tokenstring

Performing subsequent sync after initial sync

For initializing sync:

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@result = @stack..sync({'init': true});

For initializing sync with entries of a specific locale:

sync({'init': true, 'locale': 'en-us'});

For initializing sync with entries published after a specific date:

require "contentstack"; 


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment"); 

@result = @stack.sync({'init': true<span>,</span><span> </span><span>'start_date'</span><span>:</span><span> </span><span>'2018-10-22'</span>});

For initializing sync with entries of a specific content type:

require "contentstack"; 


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment"); 

@result = @stack.sync({'init': true, 'content_type_uid': 'session'});

For initializing sync with specific type:

require "contentstack"; 


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment"); 

@result = @stack.sync({'init': true, 'type': 'entry_published'});

For fetching the next batch of entries using pagination token:

require "contentstack"; 


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment"); 

@result = @stack.sync({'pagination_token': '<page_token>'});

For performing subsequent sync after initial sync:

require "contentstack"; 


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment"); 

@result = @stack.sync({'sync_token': '<sync_token>'})

SyncResult

Represents the result of a sync operation.
NameTypeDescription
skip Number

Returns the value of attribute skip.

limit Number

Returns the value of attribute limit.

items IEnumerable<dynamic>

Readonly property contains all the Contents

pagination_token String

Readonly property for paginating sync

sync_token String

Readonly property to delta sync.

total_count Number

Readonly property to check totalCount

AssetCollection

Asset class to fetch details of files on Contentstack server.



fetch

Fetch assets uploaded to the Contentstack.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@assets = @stack.assets.fetch;

Asset

Asset class to fetch file details on Conentstack server.



NameTypeDescription
uid String

Contentstack Asset UID for this asset

filename String

Name of the asset.

url String

URL to fetch/render the asset

content_type String

Content Type for the asset. image/png, image/jpeg, application/pdf, video/mp4 etc.

filesize String

Size of the asset.

tags Array

Array of tags assigned to the asset.

fetch

Fetch a particular asset using uid.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@asset = @stack.asset("asset_uid").fetch;

ContentType

ContentType provides Entry and Query instance.

fetch

A fetch is used to fetch ContentType details for specific UID.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment"); 

@content_type = @stack.content_type("content_type_uid").fetch;

entry

Retrieve a single entry with its UID.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment"); 

@content_type = @stack.content_type("content_type_uid").fetch;

query

A query that is used to query for Entry instance.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment"); 

@query = @stack.content_type("content_type_uid").query;

EntryCollection

Returns a new instance of EntryCollection.



NameTypeDescription
content_type String

Returns the value of attribute content_type.

count Number

Returns the value of attribute count.

entries Array

Returns the value of attribute entries.

Entry

An initializer is responsible for creating Entry object.
NameTypeDescription
uid (required)String

Returns the value of attribute uid.

content_type String

Returns the value of attribute content_type.

fields Object

Returns the value of attribute fields.

query Object

Returns the value of attribute query.

get

Get value for field uid

NameTypeDescription
field_uidsString

Field uid for which value to be get.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.include_reference('category')

	.fetch;

@entry.get("field_uid");

only

Specifies an array of 'only' keys in BASE object that would be 'included' in the response.

NameTypeDescription
fieldsArray

Array of the 'only' reference keys to be included in response.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.only(['title', 'description'])

	.fetch;
NameTypeDescription
fieldsString

Reference field uid for which fields to be included

fields_with_baseArray

Array of the 'only' reference keys to be included in response.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")	

	.only('category', ['title', 'description'])

	.fetch;

except

Specifies list of field uids that would be 'excluded' from the response.

NameTypeDescription
fieldsArray

Array of the 'only' reference keys to be excluded in response.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.except(['title', 'description'])

	.fetch;
NameTypeDescription
fieldsString

Reference field uid for which fields to be excluded

fields_with_baseArray

Array of the 'only' reference keys to be excluded in response.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.except('category', ['title', 'description'])

	.fetch;

include_content_type

Include object's content_type in response

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.include_content_type

	.fetch;

include_reference

Add a constraint that requires a particular reference key details.

NameTypeDescription
reference_field_uidsstring

Pass reference field that must be included in the response

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.include_reference('category')

	.fetch;
NameTypeDescription
reference_field_uidsArray
Pass array of reference fields that must be included in the response

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.include_reference(['category', 'review'])

	.fetch;

include_fallback

Include the fallback locale publish content, if specified locale content is not publish.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.include_fallback

	.fetch;

include_branch

Include the branch for publish content.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.include_branch

	.fetch;

include_embedded_items

Include Embedded Objects (Entries and Assets) along with entry/entries details.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid")

	.include_embedded_items

	.fetch;

fetch

Fetches the latest version of the entries from Contentstack.io content stack

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").entry("entry_uid").fetch;

Query

A class that defines a query that is used to query for Entry instance.

NameTypeDescription
content_type String

Returns the value of attribute content_type.

query Object

Returns the value of attribute query.

add_query

Add a custom query against specified key.

NameTypeDescription
field_uidString

Field uid to be constraint on

value(String/Number/Boolean/Hash)

Value for constraint

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.add_query('author', "Jane Doe")

	.fetch;

remove_query

Combines all the queries together using AND operator

NameTypeDescription
field_uidString

Field uid to be constraint on

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.remove_query('author')

	.fetch;

where

Add a constraint to fetch all entries that contains given value against specified key.



NameTypeDescription
query_hashHash

Query hash for equal condition

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.where({:author => "Jane Doe"})

	.fetch;

not_equal_to

Add a constraint to the query that requires a particular key's entry to be not equal to the provided value.

NameTypeDescription
field_uidString
UID of the field for which query should be executed
valueString

The object that must not be equaled.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.not_equal_to('title', 'some random title')

	.fetch;

contained_in

Add a constraint to the query that requires a particular key's entry to be contained in the provided array.

NameTypeDescription
field_uidString
UID of the field for which query should be executed
value(String/Number)

The possible values for the key's object

Array equals operator on field uid

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.contained_in("title", ["Electronics", "Apparel"])

	.fetch;

Array equals operator Within Modular Blocks

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.contained_in("additional_info.deals.deal_name", ["Electronics", "Apparel"])

	.fetch;

not_contained_in

Add a constraint to the query that requires a particular key entry's value not be contained in the provided array.

NameTypeDescription
field_uidString
UID of the field for which query should be executed
value(String/Number)

The possible values for the key's object

Array Not-equals Operator on field uid

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.not_contained_in("title", ["Electronics", "Apparel"])

	.fetch;

Array Not-equals Operator Within Modular Blocks

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.not_contained_in("additional_info.deals.deal_name", ["Electronics", "Apparel"])

	.fetch;

include_reference

Add a constraint that requires a particular reference key details.

NameTypeDescription
reference_field_uidsstring

Pass reference field that must be included in the response

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.include_reference('category')

	.fetch;
NameTypeDescription
reference_field_uidsArray
Pass array of reference fields that must be included in the response

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.include_reference(['category', 'review'])

	.fetch;

regex

Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large data sets. Example:



NameTypeDescription
field_uidstring

The key to be constrained.

patternString

The regular expression pattern to match.

optionsString

Regex options

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.regex('title', '.*Mobile.*')

	.fetch;

require "contentstack";

@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.regex('title', '.*Mobile.*', 'i')

	.fetch;

and

Combines all the queries together using AND operator

NameTypeDescription
queriesArray

Array of instances of the Query class

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");
@query1 = @stack.content_type("category").query

@query1.where("title", "Apparel")


@query2 = @stack.content_type("category").query

<span>@query2.where("title", "Apparel")</span>


query_array = [@query1, @query2]


@entries = @stack.content_type("content_type_uid").query

	.and(query_array)

	.fetch;

or

Add a constraint to fetch all entries which satisfy any queries.

NameTypeDescription
queriesArray

Array of instances of the Query class

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");
@query1 = @stack.content_type("category").query

@query1.where("title", "Apparel")


@query2 = @stack.content_type("category").query




query_array = [@query1, @query2]


@entries = @stack.content_type("content_type_uid").query

	.or(query_array)

	.fetch;

less_than

Add a constraint to the query that requires a particular key entry to be less than the provided value.

NameTypeDescription
field_uidString
UID of the field
value(String/Number)
Value used to match or compare

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.less_than('age', 20)

	.fetch;

less_than_or_equal

Add a constraint to the query that requires a particular key entry to be less than or equal to the provided value.

NameTypeDescription
field_uidString
UID of the field
value(String/Number)
Value used to match or compare

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.

('age', 20)

	.fetch;

greater_than

Add a constraint to the query that requires a particular key entry to be greater than the provided value.

NameTypeDescription
field_uidString
UID of the field
value(String/Number)
Value used to match or compare

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.greater_than('age', 20)

	.fetch;

greater_than_or_equal

Add a constraint to the query that requires a particular key entry to be greater than or equal to the provided value.

NameTypeDescription
field_uidString
UID of the field
value(String/Number)
Value used to match or compare

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.greater_than_or_equal('age', 20)

	.fetch;

limit

A limit on the number of objects to return.



NameTypeDescription
countNumber

Objects to limit in result set.

Default: 10

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.limit(20)

	.fetch;

skip

The number of objects to skip before returning any.



NameTypeDescription
countNumber

Objects to skip in result set.

Default: 10

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.skip(20)

	.fetch;

ascending

Sort the results in ascending order with the given key. Sort the returned entries in ascending order of the provided key.



NameTypeDescription
field_uidString

The key to order by

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.ascending("field_uid")

	.fetch;

descending

Sort the results in descending order with the given key. Sort the returned entries in descending order of the provided key.



NameTypeDescription
field_uidString

The key to order by

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.descending("field_uid")

	.fetch;

exists

Add a constraint that requires, a specified key exists in response.



NameTypeDescription
field_uidString

The key to be constrained.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.exists('product_image')

	.fetch;

not_exists

Add a constraint that requires, a specified key does not exists in response.



NameTypeDescription
field_uidString

The key to be constrained.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.not_exists('product_image')

	.fetch;

only

Specifies an array of 'only' keys in BASE object that would be 'included' in the response.

NameTypeDescription
fieldsArray

Array of the 'only' reference keys to be included in response.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.only(['title', 'description'])

	.fetch;
NameTypeDescription
fieldsString

Reference field uid for which fields to be included

fields_with_baseArray

Array of the 'only' reference keys to be included in response.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.only('category', ['title', 'description'])

	.fetch;

except

Specifies list of field uids that would be 'excluded' from the response.

NameTypeDescription
fieldsArray

Array of the 'only' reference keys to be excluded in response.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.except(['title', 'description'])

	.fetch;
NameTypeDescription
fieldsString

Reference field uid for which fields to be excluded

fields_with_baseArray

Array of the 'only' reference keys to be excluded in response.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.except('category', ['title', 'description'])

	.fetch;

include_count

Retrieve count and data of objects in result.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").query

	.include_count

	.fetch;

tags

Include tags with which to search entries.

NameTypeDescription
tags_arrayArray

Array of tags using which search must be performed

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.tags(["tag1", "tag2"])

	.fetch;

locale

Get entries from the specified locale.



NameTypeDescription
codeString

The locale code of the entry

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.locale("en-us")

	.fetch;

include_content_type

Include object's content_type in response

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.include_content_type

	.fetch;

include_branch

Include the branch for publish content.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entry = @stack.content_type("content_type_uid").query

	.include_branch

	.fetch;

include_fallback

Include the fallback locale publish content, if specified locale content is not publish.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.include_fallback

	.fetch;

include_embedded_items

Include Embedded Objects (Entries and Assets) along with entry/entries details.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query

	.include_embedded_items

	.fetch;

find

Fetches the array of the entries from Contentstack for specific ContentType

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query.find;

find_one

Execute a Query and get the single matching object

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@entries = @stack.content_type("content_type_uid").query.find_one;

count

Retrieve only count of entries in result.

require "contentstack";


@stack = Contentstack::Client.new("api_key", "delivery_token", "environment");

@count = @stack.content_type("content_type_uid").query.count;