Contentstack - Python Delivery SDK
Python Delivery SDK for Contentstack
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 front end, and Contentstack will take care of the rest. Read More.
Contentstack provides Python Delivery SDK to build applications on top of Python. Given below is the detailed guide and helpful resources to get started with our Python Delivery SDK.
Prerequisite
This guide will help you get started with Contentstack Python SDK to build apps powered by Contentstack.
SDK Installation and Setup
To use the Contentstack Python SDK with your existing project, perform the following steps:
- Open the terminal, create a project, and move inside it as follows:
mkdir contentstack-example cd
- Create a virtual environment:
python3 -m venv venv
- Activate the virtual environment:
source venv/bin/activate
- Install pip Contentstack as follows:
pip install contentstack
You can download the latest dependency version here
Quickstart in 5 mins
Initializing your SDK
Contentstack offers seven regions AWS North America (AWS NA), AWS Europe (AWS EU), AWS Australia (AWS AU), Azure North America (AZURE NA), Azure Europe (AZURE EU), GCP North America (GCP NA), and GCP Europe (GCP EU) as data centers to store customers' account details and data. These regions are independent of each other and therefore have a dedicated set of instructions to use SDKs offered by Contentstack.
To use SDKs for the Europe, Azure NA, or Azure EU region, you will have to make certain changes in the configuration of the SDK, as detailed below, and the rest of the instructions remain the same.
To initialize the SDK, the stack’s api_key delivery token and the name of the environment where you will publish the content, as shown in the snippet below:
import contentstack stack = contentstack.Stack(api_key='api_key', delivery_token='delivery_token', environment='environment')
Note: By default, the SDK uses the North American region. Configuration changes are not required for North American region users.
By default, the SDK uses the North American region. Configuration changes are not required for North American region users.
Refer the below code if you want to use the Europe, Azure North America, Azure Europe, GCP North America, or GCP Europe region.
import contentstack
stack = contentstack.Stack("api_key", "delivery_token", "environment", region = "ContentstackRegion.AZURE_EU")Once you have initialized the SDK, you can query entries to fetch the required content.
For Setting the branch for Europe, Azure North America, Azure Europe, GCP North America, or GCP Europe, refer the code below
For Setting Branch:
If you want to initialize SDK in a particular branch use the code given below:
import contentstack stack = contentstack.Stack(api_key='api_key', delivery_token='delivery_token',environment= 'environment', branch='branch')
Basic Queries
Contentstack SDKs let you interact with the Content Delivery APIs and retrieve content from Contentstack. They are read-only in nature. The SDKs fetch and deliver content from the nearest server via Fastly, our powerful and robust CDN.
Get a Single Entry
To retrieve a single entry from a content type, use the code snippet given below:
import contentstack
stack = contentstack.Stack(api_key='api_key', delivery_token='delivery_token', environment='environment')
contentType = stack.content_type("content_type_uid")
entry = content_type.entry("entry_uid")
response = entry.fetch()Get Multiple Entries
To retrieve multiple entries of a particular content type, use the code snippet given below:
import contentstack
stack = contentstack.Stack(api_key='api_key', delivery_token='delivery_token', environment='environment')
query = stack.content_type("content_type_uid").query()
response = query.find()Note: By default, the limit for response details per request is 100, with the maximum limit set at 250.
Pagination
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.Stack(api_key='api_key', delivery_token='delivery_token', environment='environment')
query = stack.content_type('content_type_uid').query()
response = query.locale('locale').limit(20).skip(20).find()Stack
Retrieves stack
| Name | Type | Description |
|---|---|---|
headers (required) | dict | |
early_access | dict | Optional array of header strings for early access features. |
sync_param | dict | |
endpoint | str | |
api_key (required) | str | |
delivery_token (required) | str | |
environment (required) | str | |
host | str | |
version | str | |
region | Region | DB region for your stack. You can choose from seven regions namely, AWS NA, AWS EU, AWS AU, Azure NA, Azure EU, GCP NA, and GCP EU |
timeout | int | |
branch | str | |
retry_strategy | Retry | |
live_preview_dict | dict |
live_preview_query
live_preview_query accepts key-value pair objects to the query
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); response = stack.live_preview_query(**kwargs) print(response)
image_transform
Image Delivery API covers the parameters that you can add to the URL to retrieve, manipulate (or convert) image files and display it to your web or mobile properties.
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
response = stack.image_transform("image_url", **kwargs)
print(response)sync_token
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
response = stack.sync_token("sync_token")
print(response)pagination
import contentstack
stack = contentstack.Stack(api_key = 'api_key', access_token = 'access_token', environment = 'environment')
result = stack.pagination('pagination_token')
if result is not None:
logger.info(result)
# result.items: Contains sync data
# result.paginationToken: For fetching the next batch of entries using pagination token
# result.syncToken: For performing subsequent sync after initial sync
else:
logger.error(result)asset_query
initial sync of the stack
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); response = stack. ( ) print( )
asset_query
assets of the stack
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); assets = stack.asset_query() print( )
asset
asset of the stack
import contentstack;
stack = contentstack.Stack('api_key', 'delivery_token', 'environment');
asset = stack.asset("uid")
print(asset)get_live_preview
live_preview for the stack
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); result = stack.get_live_preview print(result)
get_headers
headers for the stack
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); result = stack.get_headers print(result)
get_branch
branch for the stack
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); result = stack.get_branch print(result)
get_environment
environment for the stack
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); result = stack.get_environment print(result)
get_delivery_token
Delivery Token for the stack
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); result = stack.get_delivery_token print(result)
get_api_key
api_key for the stack
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment) result = stack.get_api_key print(result)
early_access
Array of header strings for early access features.
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment, early_access=["early_access_1", "early_access_2"]);
Asset
Retrieves a single asset, specify its UID.
| Name | Type | Description |
|---|---|---|
uid | str | Readonly property to check value of asset’s uid |
fetch
This call fetches the latest version of a specific asset of a particular stack
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); asset = stack.asset(uid='asset_uid') response = asset.fetch()
include_fallback
Retrieve the published content of the fallback locale if an entry is not localized in specified locale
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); asset = stack.asset(uid='asset_uid') asset = asset.include_fallback()
include_dimension
Include the dimensions (height and width) of the image in the response. Supported image types: JPG, GIF, PNG, WebP, BMP, TIFF, SVG, and PSD
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); asset = stack.asset(uid='asset_uid') asset = asset.include_dimension()
include_metadata
Includes asset metadata along with response body.
import contentstack
stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
response = stack.asset('asset_uid').include_metadata().find()
print(response)relative_urls
Include the relative URLs of the assets in the response
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); asset = stack.asset(uid='asset_uid') asset = asset.relative_urls()
environment
Provide the name of the environment if you wish to retrieve the assets published in a particular environment
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
asset = asset.environment('environment_name')params
params is used to pass additional parameters to the asset query
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
asset = asset.param('key', 'value')remove_environment
Removes environment from the request params
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset = stack.asset(uid='asset_uid')
asset = asset.
('production')AssetQuery
Retrieves Assets
| Name | Type | Description |
|---|---|---|
asset_query_params | dict | Readonly property to get data of entry. |
find
This call fetches the list of all the assets of a particular stack. It also returns the content of each asset in dict format.
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); asset_query = stack.asset_query() response = stack.asset_query().find()
locale
Enter locale code. e.g., en-us
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
asset_query = stack.asset_query()
stack.asset_query().locale("locale_code")include_fallback
Retrieve the published content of the fallback locale if an entry is not localized in specified locale
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); asset_query = stack.asset_query() stack.asset_query(). ()
include_metadata
Includes AssetQuery metadata along with response body.
import contentstack
stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
result = stack.assetQuery().include_metadata().find()
print(result)relative_url
include the relative URLs of the assets in the response
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); asset_query = stack.asset_query() stack.asset_query().relative_url()
include_branch
Includes branch in the response
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); asset_query = stack.asset_query() stack.asset_query(). ()
version
Specify the version number of the asset that you wish to retrieve. If the version is not specified, the details of the latest version will be retrieved. To retrieve a specific version, keep the environment parameter blank
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); asset_query = stack.asset_query() asset_query.version(version)
environment
Provide the name of the environment if you wish to retrieve the assets published in a particular environment
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment);
ContentType
query
We can query on entry of specified ContentType
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()fetch
This method is useful to fetch ContentType of the stack
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
response = content_type.fetch()find
This method is useful to fetch ContentType of the of the stack.
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
response = content_type.find()entry
An entry is the actual piece of content created using one of the defined content types
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')Entry
Retrieves assets
| Name | Type | Description |
|---|---|---|
entry_params | dict | Readonly property to get data of entry. |
content_type_id | str | |
entry_uid | str | |
base_url | str |
fetch
Fetches the latest version of the entries from stack
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
response = entry.fetch()include_embedded_items
include_embedded_items instance of Entry include_embedded_objects (Entries and Assets) along with entry/entries details
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.include_embedded_items()include_branch
Retrieve the published pranch in the entry response
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.include_branch()include_fallback
Retrieve the published content of the fallback locale if an entry is not localized in specified locale
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.
include_metadata
Includes entry metadata along with response body.
import contentstack
stack = contentstack.Stack('api_key','delivery_token','environment')
content_type = stack.content_type('contenttype_uid').
result = content_type.entry('entry_uid').include_metadata().find()
print(result)param
This method is useful to add additional Query parameters to the entry
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.param("key", "value")version
When no version is specified, it returns the latest version, To retrieve a specific version, specify the version number under this parameter. In such a case, DO NOT specify any environment
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.version(number)environment
Enter the name of the environment of which the entries needs to be included
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
entry = content_type.entry(uid='entry_uid')
entry.environment('environment_name')Entry Variants
Entry Variants let you create different versions of content for specific audiences, languages, or marketing experiments. Each variant is grouped under a Base Entry—the original content item. Entry Variants are the tailored versions, and all variants are organized into a Variant Group. This setup makes it easier to manage personalized content, maintain consistency, and apply updates across all versions efficiently.
Get All Entry Variants
The Get all entry variants request retrieves all entry variants of the specified entry.
To fetch specific variants, pass one or more variant UIDs in the x-cs-variant-uid header. This returns only the variants applied to the specified entries.
Note: You can add up to three variant UIDs in the x-cs-variant-uid header, separated by commas. The first UID in the list has the highest priority and its content will be used first.
>For example, if you enter Red, Green, and Blue in that order, Red will be given priority.
Example: x-cs-variant-uid: cs6c42daef493fb432, cs7697ce80c9bbcc3e, cs8697ce80c9bbcc4f
You can add other Queries to extend the functionality of this API call.
- The API timeout for entry variants is capped at 10 seconds.
- The maximum response document size for all entry variants is 10 MB
Example 1:
import contentstack
stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
content_type = stack.content_type(content_type_uid)
response = content_type.variants('variants_uid1').find()
Example 2:
import contentstack
stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
content_type = stack.content_type(content_type_uid)
response = content_type.variants(['variants_uid_1', 'variants_uid_2', 'variants_uid_3' ]).find()Get a Single Entry Variants
The Get a single entry variant request retrieves a single variant entry of a given base entry.
To fetch variants applied to your entries, pass the the variant UID(s) in the x-cs-variant-uid header.
Note: You can add up to three variant UIDs in the x-cs-variant-uid header, separated by commas. The first UID in the list has the highest priority and its content will be used first. For example, if you enter Red, Green, and Blue in that order, Red will be given priority.Example: x-cs-variant-uid: cs6c42daef493fb432, cs7697ce80c9bbcc3e, cs8697ce80c9bbcc4f
You can add other Queries to extend the functionality of this API call.
- The API timeout for entry variants is capped at 10 seconds.
- The maximum response document size for all entry variants is 10 MB
Example 1:
import contentstack
stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
entry = stack.content_type(content_type_uid).entry('entry_uid')
response = entry.variants('variants_uid1').fetch()
)
Example 2:
import contentstack
stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
entry = stack.content_type(content_type_uid).entry('entry_uid')
response = entry.variants(['variants_uid_1', 'variants_uid_2', 'variants_uid_3' ]).fetch()
Global Fields
A Global field is a reusable field or group of fields that you define once and reuse across any content type in your stack. This helps you avoid recreating the same set of fields multiple times, saving time and effort.
fetch
The fetch method retrieves data for the specified global field.
Example:
import contentstack
stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
global_field = stack.global_field('global_field_uid')
response = global_field.fetch()
find
The find method retrieves all global fields in the stack.
Example:
import contentstack
stack = contentstack.Stack('api_key', 'delivery_token', 'environment')
some_dict = {'abc':'something'}
global_field = stack.global_field('global_field_uid')
response = global_field.find(param=some_dict)Query
Retrieves assets
| Name | Type | Description |
|---|---|---|
content_type_uid | str | |
base_url | str |
query
Adds key value pairs to the to the query parameters
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query = query.query("key":"value")addParams
Adds Query Parameters to the to the request
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query = query.addParam({"key":"value"})param
Adds Query Parameters to the to the request
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query = query.param("key", "value")order_by_descending
you can sort them in the descending order with respect to the value of a specific field in the response body
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.order_by_descending("key")order_by_ascending
you can sort them in the ascending order with respect to the value of a specific field in the response body.
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.order_by_ascending("key")limit
A limit on the number of objects to return./p>
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.limit(count)skip
The number of objects to skip before returning any. skip_count No of objects to skip from returned objects
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.skip(count)include_count
Retrieve count and data of objects in result
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query()
query.include_count()where
Get entries containing the field values matching the condition in the query
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
content_type = stack.content_type('content_type_uid')
query = content_type.query("
",
)
query.where()add_param
This method adds key and value to the Query
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.add_param("key","value")include_reference_content_type_uid
This method also includes the content type UIDs of the referenced entries returned in the response
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.
()include_content_type
This method also includes the ContentType in the entry
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.include_content_type()include_reference
When you fetch an entry of a content type that has a reference field, by default, the content of the referred entry is not fetched. It only fetches the UID of the referred entry, along with the content of the specified entry
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.include_reference()excepts
Specifies list of field_uid that would be excluded from the response. It refers to the top-level fields of the schema
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.excepts()only
Specifies an array of only keys in BASE object that would be included in the response. It refers to the top-level fields of the schema
Example 1:
Displays values of the specified fields of entries or assets in the response.
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.only("title")Example 2:
The only function with an array of field UIDs will include data of mentioned fields and exclude the data of all other fields for each entry.
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type('demo').query().add_param('only[BASE][]', ['title','description'])
response = query.find()find_one
It fetches single query response
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
response = query.find_one()locale
Language code of which the entries need to be included. Only the entries published in this locale will be displayed
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
response = query.locale()find
It fetches the query response
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
response = query.find()include_embedded_items
Retrieve the published pranch in the response
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.include_embedded_items()include_branch
Retrieve the published pranch in the response
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.
()include_fallback
Retrieve the published content of the fallback locale if an entry is not localized in specified locale
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
include_metadata
Includes Query metadata along with response body.
import contentstack
stack = contentstack.Stack('api_key','delivery_token','environment')
query = stack.content_type('contenttype_uid').query()
result = query.include_metadata().find()
print(result)where_not_in
Get entries having values based on referenced fields. This query works the opposite of $in_query and retrieves all entries that does not satisfy query conditions made on referenced fields.
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query.where_not_in("brand")where_in
Get entries having values based on referenced fields. This query retrieves all entries that satisfy the query conditions made on referenced fields
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query = query.where_in("brand")search
This method provides only the entries matching the specified value.
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query = stack.content_type("content_type_uid").query()
query = query.search("search_keyword")tags
Include tags with which to search entries that accept variable-length argument lists
import contentstack; stack = contentstack.Stack(api_key, delivery_token, environment); response = query.fetch()
query_operator
query_operator Get entries that satisfy all the conditions provided in the '$and' query.
import contentstack;
stack = contentstack.Stack(api_key, delivery_token, environment);
query1 = stack.content_type("content_type_uid_1").query()
query2 = self.query1.where("price", QueryOperation.IS_LESS_THAN, fields=90)