Entry

add_param adds an arbitrary query parameter to the inherited parameter store.

The same entry, for chaining.

Validation

• There is no client-side validation that raises. add_param records the pair only when neither argument is None, and returns the instance untouched otherwise.
• Passing None as either argument records nothing and raises nothing, so a null key produces a request that silently lacks the parameter you meant to send.
• An empty string is not None, so add_param('', '') records a parameter with no name.
• Any value type reaches the store as it stands. The annotation says str, and the method applies no conversion and no check, so a list, an integer, or a dictionary records fine.
• Omitting either argument raises TypeError immediately, because both are positional parameters with no default.
• Errors that do occur come from the fetch() call that follows, not from add_param().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, an unrecognized parameter name) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. add_param records the pair in the inherited parameter dictionary and makes no request.
• Wins over param on a key collision, whatever order you called them in, because fetch merges the inherited dictionary last. See Two parameter stores on the Entry class page.
• Shares one namespace with every inherited method, so add_param('locale', 'en-us') and locale('fr-fr') write the same key and the later call wins.
• Accepts a list, which fetch expands into one pair per item. This is the route to a multi-value parameter such as only[BASE][], which the only method cannot express.
• Applies no string conversion, so a Python True reaches the query string as True. Pass the literal 'true' when the API expects the lowercase form.
• Entry and the Query class both inherit this method from EntryQueryable, so it behaves the same on an entry query.

Example

Basic usage: send a parameter the SDK has no method for

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .add_param('include_dimension', 'true') \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry']['hero_image'].get('dimension'))

All parameters: both arguments carrying a list value

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # The list expands into only[BASE][]=title&only[BASE][]=url&only[BASE][]=price.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .add_param('only[BASE][]', ['title', 'url', 'price']) \
        .fetch()
    print(result['entry'].keys())
except Exception as error:
    print('Request failed:', error)

Edge case: a null key records nothing and raises nothing

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

user_supplied_key = None

try:
    # No parameter reaches the request, and no exception reports the omission.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .add_param(user_supplied_key, 'true') \
        .fetch()
except Exception as error:
    print('Request failed:', error)

Edge case: add_param overrides param on the same key

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # fetch merges the inherited store last, so this request carries locale=fr-fr.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .add_param('locale', 'fr-fr') \
        .param('locale', 'en-us') \
        .fetch()
    print('locale:', result['entry']['locale'])
except Exception as error:
    print('Request failed:', error)

asset_fields adds optional asset fields to the assets in the response.

The same entry, for chaining.

Validation

• There is no client-side validation. asset_fields accepts any value and converts each one with str, so a misspelled field name reaches the query string as given.
• Calling it with no arguments records nothing and raises nothing. The method tests the argument tuple for truthiness first and returns the instance untouched.
• A list or a tuple among the arguments flattens into its items, so asset_fields(['embedded_metadata']) and asset_fields('embedded_metadata') record the same thing.
• Errors that do occur come from the fetch() call that follows, not from asset_fields().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, a field name the API does not recognize) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. asset_fields appends the names to a list under the asset_fields[] key in the inherited parameter dictionary and makes no request.
• Accumulates rather than replaces. Each call appends to the list already there, so two calls send both sets and a repeated name reaches the query string twice.
• The SDK documents four accepted names: user_defined_fields, embedded_metadata, ai_generated_metadata, and visual_markups.
• The stored list expands into one asset_fields[] pair per item. See A list value expands into repeated query keys on the Entry class page.
• Applies to the assets the response already carries. It adds no assets of its own.
• Entry overrides this method and delegates straight to the EntryQueryable implementation, so it behaves the same on an entry query.

Limitations

• Does not remove a name once recorded. Build a fresh Entry to change the set.

Example

Basic usage: add one asset field

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .asset_fields('user_defined_fields') \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry']['hero_image'])

All four field names in one call

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # Each name becomes its own asset_fields[] pair in the query string.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .asset_fields(
            'user_defined_fields',
            'embedded_metadata',
            'ai_generated_metadata',
            'visual_markups',
        ) \
        .fetch()
    print(result['entry']['hero_image'].keys())
except Exception as error:
    print('Request failed:', error)

Building the set across two calls

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

show_markups = True

entry = stack.content_type('products').entry('<ENTRY_UID>')
entry = entry.asset_fields('user_defined_fields')

if show_markups:
    entry = entry.asset_fields('visual_markups')

try:
    # Both names travel on the request, because the second call appends.
    result = entry.fetch()
except Exception as error:
    print('Request failed:', error)

Edge case: an empty call records nothing

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

selected_fields = []

try:
    # An empty argument list is a no-op, so the request carries no asset_fields[] pair.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .asset_fields(*selected_fields) \
        .fetch()
except Exception as error:
    print('Request failed:', error)

environment sets the publishing environment the request targets.

The same entry, for chaining.

Validation

• Passing None raises KeyError with the message "Invalid environment. Provide a valid environment and try again." A null environment would replace the header the Stack already holds with nothing usable.
• Nothing else fails a check. An empty string, an integer, or a name that matches no environment reaches the header as given.
• Omitting the argument raises TypeError immediately, because environment is a positional parameter with no default.
• Errors that do occur come from the fetch() call that follows, not from environment().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, a name that matches no environment) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. environment writes the value into the request headers and makes no request.
• The headers belong to the Stack, not to this entry. Every object built from that Stack shares them, so the value stays in place for later requests until remove_environment deletes it or another environment call replaces it. See The environment travels in the request headers on the Entry class page.
• fetch copies the header value into the query string as well, so the request carries the environment in both places.
• Stack already sets this header from its third constructor argument. Call environment only when one entry needs a different environment from the rest of the stack.
• Calling environment twice replaces the first value.

Example

Basic usage: read an entry from a named environment

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .environment('production') \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry']['title'])

Error handling: a null environment raises at the call site

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

selected_environment = None

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .environment(selected_environment) \
        .fetch()
except KeyError as error:
    # Fires on environment itself, before any request goes out.
    print('Invalid environment:', error)

Edge case: the value outlives the entry that set it

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # This call rewrites the shared Stack header.
    staged = stack.content_type('products').entry('<ENTRY_UID>').environment('staging').fetch()

    # The second entry still targets staging, because nothing reset the header.
    other = stack.content_type('products').entry('<OTHER_ENTRY_UID>').fetch()

    # Chain remove_environment, or set the environment again, to control it.
    restored = stack.content_type('products') \
        .entry('<OTHER_ENTRY_UID>') \
        .environment('production') \
        .fetch()
except Exception as error:
    print('Request failed:', error)

excepts drops one top-level field from the response and keeps the rest.

The same entry, for chaining.

Validation

• Passing a value that is not a string raises KeyError with the message "Invalid field UID. Provide a valid UID and try again." This includes a list, so excepts(['price', 'stock']) raises rather than dropping two fields.
• Passing None raises nothing and records nothing. excepts tests for None first and returns the instance untouched, so a null field UID produces a full response instead of an error.
• An empty string clears the check and reaches the query string as an empty value.
• Omitting the argument raises TypeError immediately, because field_uid is a positional parameter with no default.
• Errors that do occur come from the fetch() call that follows, not from excepts().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, a field UID the content type does not define) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. excepts records the field UID under the except[BASE][] key in the inherited parameter dictionary and makes no request.
• Applies to the top-level fields of the schema, which is how the SDK documents the BASE object in the key it writes.
• Holds one value. A second excepts call replaces the first, because both write the same key.
• The method name carries the trailing s. except is a reserved word in Python, so the SDK could not use it.
• Combining excepts with only sends both parameters. The API decides the outcome, and the SDK applies no precedence of its own.

Limitations

• Does not accept several field UIDs. Pass a list through the add_param method under the same except[BASE][] key, which fetch expands into one pair per item.

Example

Basic usage: drop one field

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .excepts('internal_notes') \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print('internal_notes' in result['entry'])

Several fields: pass the list through add_param

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # add_param applies no type check, and fetch expands the list into repeated keys.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .add_param('except[BASE][]', ['internal_notes', 'draft_copy']) \
        .fetch()
    print(result['entry'].keys())
except Exception as error:
    print('Request failed:', error)

Error handling: a list raises at the call site

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .excepts(['internal_notes', 'draft_copy']) \
        .fetch()
except KeyError as error:
    # Fires on excepts itself, because the method accepts a string and nothing else.
    print('Pass one field UID as a string:', error)

Edge case: a null field UID drops nothing

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

excluded_field = None

try:
    # excepts records nothing here, so the response carries every field.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .excepts(excluded_field) \
        .fetch()
    print('fields returned:', len(result['entry']))
except Exception as error:
    print('Request failed:', error)

fetch retrieves one published entry by its UID.

The requested entry under the entry key, or the merged entries on a live preview request.

Validation

• fetch validates nothing itself. The two UID checks happen earlier, in the factory call that built the instance.
• content_type.entry('') reaches this method. The empty string clears the factory check, so fetch sends a URL ending in /entries/. See the Warning on the Entry class page.
• A live_preview dictionary with no enable key raises KeyError, because fetch indexes that key directly before it makes the request.
• A live_preview dictionary carrying enable: False raises ValueError with the message "Missing required keys in live preview data. Provide all required keys and try again." fetch takes the merge path whenever live_preview holds anything other than None, and the preview response it needs never arrives. The same ValueError fires when the content_type_uid in the dictionary names a different content type, or when the preview request itself returns an error_code.
• A merge whose entry payload is not a list of dictionaries raises TypeError with the message "Invalid entry_response format. Provide a list of dictionaries, each containing entry data, and try again."
• fetch raises an exception only for network failures (timeout, DNS error, dropped connection). The exception type is RequestError.
  • An API-level rejection, including a UID that names no entry, returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Calls GET /content_types/{content_type_uid}/entries/{entry_uid} and makes one HTTP request per call.
• Returns the whole response body as a dictionary on the normal path, so read the content from the entry key. fetch returns the envelope rather than the contents of that key, which differs from Taxonomy.fetch.
• Assembles the query string in three steps.
  • Copies the environment header into the parameters when that header exists.
  • Merges the inherited parameter dictionary over the entry's own. See Two parameter stores on the Entry class page.
  • Serializes the result with doseq=True, so a list value produces one pair per item.
• Live preview changes the return type. When the Stack carries a live_preview dictionary, fetch requests the preview entry first and then returns a list of merged entries rather than the response dictionary.
  • fetch sends the authorization header when the dictionary carries management_token, and the preview_token header otherwise.
  • The preview request runs only when enable is truthy and content_type_uid matches this entry's content type.
  • The merge matches entries on their uid and overwrites each field in the published entry with the preview value.
• Calling fetch twice on one instance repeats the same request. The instance keeps every modifier you chained.

Limitations

• Does not return more than one entry. Use the Query object that content_type.query() returns to read several entries in one request.
• Does not resolve reference fields unless you name them. Chain the include_reference method to name the fields to resolve.
• Does not return the variants of the entry. Use the variants method to reach them.

Example

Basic usage: read one entry by UID

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products').entry('<ENTRY_UID>').fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry']['uid'], result['entry']['title'])

All modifiers: locale, references, embedded items, and a raw parameter

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .locale('fr-fr') \
        .include_fallback() \
        .include_reference(['categories', 'brand']) \
        .include_embedded_items() \
        .include_branch() \
        .param('include_dimension', 'true') \
        .fetch()
    print('branch:', result['entry'].get('_branch'))
except Exception as error:
    print('Request failed:', error)

Error handling: an unknown UID does not raise

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products').entry('no_such_entry').fetch()
except Exception as error:
    print('Request failed:', error)
else:
    # A missing entry arrives as an ordinary return value, not an exception.
    if 'error' in result:
        print('code:', result.get('error_code'), 'message:', result.get('error_message'))

Edge case: live preview returns a list instead of a dictionary

import contentstack

stack = contentstack.Stack(
    '<API_KEY>',
    '<DELIVERY_TOKEN>',
    '<ENVIRONMENT>',
    live_preview={
        'enable': True,
        'preview_token': '<PREVIEW_TOKEN>',
        'content_type_uid': 'products',
        'entry_uid': '<ENTRY_UID>',
    },
)
stack.live_preview_query(live_preview_query={'live_preview': '<PREVIEW_HASH>'})

try:
    result = stack.content_type('products').entry('<ENTRY_UID>').fetch()
except ValueError as error:
    # Fires when the preview response never arrives, for example when enable is False
    print('Live preview is incomplete:', error)
else:
    # A live preview request returns a list of merged entries, so index into it.
    print(result[0]['title'])

include_branch adds the _branch field to the entry in the response.

The same entry, for chaining.

Validation

• There is no client-side validation and nothing to reject. include_branch writes one fixed flag and cannot fail.
• Errors that do occur come from the fetch() call that follows, not from include_branch().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. include_branch records the include_branch parameter as the string true in the entry's own parameter dictionary and makes no request.
• Reports the branch the entry came from. It does not choose one. The branch itself travels in the branch header, which Stack sets from its branch argument.
• Adds a _branch field to the entry in the response. Read it with get, because a stack without branches has nothing to report there.
• Calling it twice changes nothing. The flag already holds true.
• The variants method takes its own branch argument, which scopes that request through a header rather than through this flag.

Example

Basic usage: report the branch the entry came from

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_branch() \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print('branch:', result['entry'].get('_branch'))

Reading from a named branch: set the branch on the Stack

import contentstack

stack = contentstack.Stack(
    '<API_KEY>',
    '<DELIVERY_TOKEN>',
    '<ENVIRONMENT>',
    branch='development',
)

try:
    # The Stack argument selects the branch, and the flag reports it back.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_branch() \
        .fetch()
    print('branch:', result['entry'].get('_branch'))
except Exception as error:
    print('Request failed:', error)

Edge case: a stack without branches reports nothing

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products').entry('<ENTRY_UID>').include_branch().fetch()

    # Use get, because the field can be absent rather than empty.
    print('branch:', result['entry'].get('_branch', 'not reported'))
except Exception as error:
    print('Request failed:', error)

include_content_type adds the content type schema of the entry to the response.

The same entry, for chaining.

Validation

• There is no client-side validation and nothing to reject. include_content_type writes two fixed flags and cannot fail.
• Errors that do occur come from the fetch() call that follows, not from include_content_type().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. include_content_type records two flags in the inherited parameter dictionary and makes no request.
• Sets two parameters, not one: include_content_type and include_global_field_schema, both to the string true. The second one has no method of its own, so this call is the only route to it.
• Adds a content_type key alongside entry in the response body.
• Calling it twice changes nothing. Both flags already hold true.

Example

Basic usage: read the entry with its schema

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_content_type() \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        for field in result['content_type']['schema']:
            print(field['uid'], field['data_type'])

With referenced content types: schema plus reference identity

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_content_type() \
        .include_reference(['categories']) \
        .include_reference_content_type_uid() \
        .fetch()
    print('schema fields:', len(result['content_type']['schema']))
except Exception as error:
    print('Request failed:', error)

Edge case: the global field schema arrives with it

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # One call sends include_content_type=true and include_global_field_schema=true.
    result = stack.content_type('products').entry('<ENTRY_UID>').include_content_type().fetch()

    # A global field in the schema carries its nested definition, not just a UID.
    print(result['content_type']['schema'])
except Exception as error:
    print('Request failed:', error)

include_embedded_items resolves the entries and assets embedded in the entry's rich text fields.

The same entry, for chaining.

Validation

• There is no client-side validation and nothing to reject. include_embedded_items writes one fixed value and cannot fail.
• Errors that do occur come from the fetch() call that follows, not from include_embedded_items().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. include_embedded_items records the include_embedded_items[] key with the value BASE in the entry's own parameter dictionary and makes no request.
• BASE is the only value the method sends. The SDK exposes no way to name a different scope, so use the param or the add_param method when you need one.
• Adds an _embedded_items key to the entry in the response, holding the embedded entries and assets the rich text references.
• Calling it twice changes nothing. The key already holds BASE.

Limitations

• Does not resolve reference fields. A reference field is a separate mechanism, so chain the include_reference method for those.

Example

Basic usage: resolve embedded entries and assets

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('blog_post') \
        .entry('<ENTRY_UID>') \
        .include_embedded_items() \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry'].get('_embedded_items'))

With references: two resolution mechanisms in one request

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('blog_post') \
        .entry('<ENTRY_UID>') \
        .include_embedded_items() \
        .include_reference(['author']) \
        .fetch()
    entry = result['entry']
    print(entry['author'][0]['title'], entry.get('_embedded_items'))
except Exception as error:
    print('Request failed:', error)

Edge case: send a different scope through param

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # include_embedded_items sends BASE only, so write the key directly for anything else.
    result = stack.content_type('blog_post') \
        .entry('<ENTRY_UID>') \
        .param('include_embedded_items[]', 'body') \
        .fetch()
except Exception as error:
    print('Request failed:', error)

include_fallback returns an earlier locale in the hierarchy when the entry has no localization in the requested locale.

The same entry, for chaining.

Validation

• There is no client-side validation and nothing to reject. include_fallback writes one fixed flag and cannot fail.
• Errors that do occur come from the fetch() call that follows, not from include_fallback().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. include_fallback records the include_fallback parameter as the string true in the entry's own parameter dictionary and makes no request.
• include_fallback prints the line "Requesting fallback content for the specified locale." to standard output on every call. The SDK offers no flag to suppress it, so a service that parses its own stdout needs to account for the line.
• Pair it with the locale method. Without a locale on the request there is no localization to fall back from.
• The response carries a locale field naming the localization the API actually returned. Compare it against the code you requested to detect a fallback.
• Calling it twice changes nothing. The flag already holds true.

Example

Basic usage: accept an earlier locale in the hierarchy

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .locale('fr-ca') \
        .include_fallback() \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry']['locale'], result['entry']['title'])

Detecting a fallback: compare the requested locale against the returned one

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

requested_locale = 'fr-ca'

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .locale(requested_locale) \
        .include_fallback() \
        .fetch()

    if result['entry']['locale'] != requested_locale:
        print('served from', result['entry']['locale'])
except Exception as error:
    print('Request failed:', error)

Edge case: the method writes a line to standard output

import contentstack
import io
import contextlib

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

captured = io.StringIO()

try:
    # Redirect stdout around the call when the extra line breaks your log format.
    with contextlib.redirect_stdout(captured):
        entry = stack.content_type('products').entry('<ENTRY_UID>').include_fallback()
    result = entry.locale('fr-ca').fetch()
except Exception as error:
    print('Request failed:', error)

include_metadata adds the entry metadata to the response.

The same entry, for chaining.

Validation

• There is no client-side validation and nothing to reject. include_metadata writes one fixed flag and cannot fail.
• Errors that do occur come from the fetch() call that follows, not from include_metadata().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. include_metadata records the include_metadata parameter as the string true in the inherited parameter dictionary and makes no request.
• Adds a _metadata key to the entry in the response.
• The SDK returns the metadata as the API sends it and reads none of it, so treat the shape as loosely typed.
• Calling it twice changes nothing. The flag already holds true.

Example

Basic usage: read the entry with its metadata

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_metadata() \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry'].get('_metadata'))

With the branch flag: metadata plus publishing context

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_metadata() \
        .include_branch() \
        .fetch()
    entry = result['entry']
    print(entry.get('_branch'), entry.get('_metadata'))
except Exception as error:
    print('Request failed:', error)

Edge case: read the key defensively

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products').entry('<ENTRY_UID>').include_metadata().fetch()

    # The SDK adds no key of its own, so use get rather than an index.
    metadata = result['entry'].get('_metadata', {})
    print('metadata keys:', list(metadata))
except Exception as error:
    print('Request failed:', error)

include_reference resolves the named reference fields instead of returning their UIDs.

The same entry, for chaining.

Validation

• There is no client-side validation that raises. include_reference records the value only when it is a string or a list, and returns the instance untouched for anything else.
• Passing None, an integer, a dictionary, or a tuple records nothing and raises nothing. The response then carries the reference UIDs rather than the referenced content, with no error to explain it.
• Omitting the argument raises TypeError immediately, because field_uid is a positional parameter with no default.
• Errors that do occur come from the fetch() call that follows, not from include_reference().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, a field UID that is not a reference field) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. include_reference records the value under the include[] key in the inherited parameter dictionary and makes no request.
• A list value expands into one include[] pair per item, because fetch serializes the parameters with doseq=True. See A list value expands into repeated query keys on the Entry class page.
• Holds one value. A second include_reference call replaces the first, so pass every field in a single list rather than chaining the method twice.
• Without this call the response carries the UID of each referenced entry and none of its content.

Limitations

• Does not resolve every reference at once. Name each reference field you want.
• Does not exceed the depth the SDK documents. A Reference field that points at several content types works to three levels of nesting.
• Does not resolve entries and assets embedded in rich text. Use the include_embedded_items method for those.

Example

Basic usage: resolve one reference field

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_reference('categories') \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        for category in result['entry']['categories']:
            print(category['title'])

A list of fields: resolve several references in one request

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # The list becomes include[]=categories&include[]=brand in the query string.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_reference(['categories', 'brand']) \
        .include_reference_content_type_uid() \
        .fetch()
    print(result['entry']['brand'][0]['_content_type_uid'])
except Exception as error:
    print('Request failed:', error)

Edge case: an unsupported type records nothing and raises nothing

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

reference_fields = ('categories', 'brand')

try:
    # A tuple is neither a string nor a list, so the call has no effect.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_reference(reference_fields) \
        .fetch()

    # categories arrives as a list of UIDs, not resolved entries.
    print(result['entry']['categories'])
except Exception as error:
    print('Request failed:', error)

Edge case: a second call replaces the first

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # Only brand is resolved here, because both calls write the include[] key.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_reference('categories') \
        .include_reference('brand') \
        .fetch()
except Exception as error:
    print('Request failed:', error)

include_reference_content_type_uid adds the content type UID of each referenced entry to the response.

The same entry, for chaining.

Validation

• There is no client-side validation and nothing to reject. include_reference_content_type_uid writes one fixed flag and cannot fail.
• Errors that do occur come from the fetch() call that follows, not from include_reference_content_type_uid().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. include_reference_content_type_uid records the include_reference_content_type_uid parameter as the string true in the inherited parameter dictionary and makes no request.
• Adds a _content_type_uid key to each referenced entry in the response.
• Pair it with the include_reference method. This flag identifies the resolved references, so it adds nothing to a response that carries reference UIDs alone.
• Useful when a reference field points at several content types, because the flag is what tells the two apart in the returned list.
• Calling it twice changes nothing. The flag already holds true.

Example

Basic usage: identify the content type of each referenced entry

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_reference(['related_content']) \
        .include_reference_content_type_uid() \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        for item in result['entry']['related_content']:
            print(item['_content_type_uid'], item['uid'])

Branching on the content type of a mixed reference field

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_reference(['related_content']) \
        .include_reference_content_type_uid() \
        .fetch()

    for item in result['entry']['related_content']:
        if item['_content_type_uid'] == 'blog_post':
            print('post:', item['title'])
        else:
            print('other:', item['uid'])
except Exception as error:
    print('Request failed:', error)

Edge case: the flag adds nothing without resolved references

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # Nothing resolves the reference field here, so related_content stays a UID list.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .include_reference_content_type_uid() \
        .fetch()
    print(result['entry']['related_content'])
except Exception as error:
    print('Request failed:', error)

locale sets the language the request targets.

The same entry, for chaining.

Validation

• There is no client-side validation. locale records whatever you pass, including None, an empty string, or a locale code the stack does not have.
• Passing None sends the text None as the value, because fetch serializes the stored value without a null check. Guard the code before you call locale when it comes from user input.
• Omitting the argument raises TypeError immediately, because locale is a positional parameter with no default.
• Errors that do occur come from the fetch() call that follows, not from locale().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, a locale code the stack does not have) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. locale records the code in the inherited parameter dictionary and makes no request. fetch sends it on that call.
• Omitting locale sends no locale parameter, and the API applies its own default.
• Returns only the localization published in that locale. Chain the include_fallback method to accept an earlier locale in the hierarchy when this one has no published localization.
• locale writes to the inherited store, which fetch merges last, so it overrides param with the key locale whatever order you called them in. See Two parameter stores on the Entry class page.
• Calling locale twice replaces the first code. The SDK stores it under a single key.
• Entry and the Query class both inherit this method from EntryQueryable, so it behaves the same on an entry query.

Example

Basic usage: read the French localization of an entry

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .locale('fr-fr') \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry']['locale'], result['entry']['title'])

With a fallback: accept an earlier locale when this one has no localization

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .locale('fr-ca') \
        .include_fallback() \
        .fetch()
    # Compare the returned locale against the requested one to detect a fallback.
    print('returned locale:', result['entry']['locale'])
except Exception as error:
    print('Request failed:', error)

Edge case: a null locale reaches the query string as text

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

selected_locale = None

try:
    # This sends locale=None as text. Guard the value before the call.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .locale(selected_locale) \
        .fetch()
    if 'error' in result:
        print('code:', result.get('error_code'))
except Exception as error:
    print('Request failed:', error)

only keeps one top-level field in the response and drops the rest.

The same entry, for chaining.

Validation

• Passing a value that is not a string raises KeyError with the message "Invalid field UID. Provide a valid UID and try again." This includes a list, so only(['title', 'url']) raises rather than selecting two fields.
• Passing None raises nothing and records nothing. only tests for None first and returns the instance untouched, so a null field UID produces a full response instead of an error.
• An empty string clears the check and reaches the query string as an empty value.
• Omitting the argument raises TypeError immediately, because field_uid is a positional parameter with no default.
• Errors that do occur come from the fetch() call that follows, not from only().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, a field UID the content type does not define) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. only records the field UID under the only[BASE][] key in the inherited parameter dictionary and makes no request.
• Applies to the top-level fields of the schema, which is how the SDK documents the BASE object in the key it writes.
• Holds one value. A second only call replaces the first, because both write the same key.
• only writes to the inherited store, which fetch merges last, so it overrides a param call using the same key. See Two parameter stores on the Entry class page.
• Combining only with excepts sends both parameters. The API decides the outcome, and the SDK applies no precedence of its own.

Limitations

• Does not accept several field UIDs. Pass a list through the add_param method under the same only[BASE][] key, which fetch expands into one pair per item.

Example

Basic usage: keep one field

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .only('title') \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry'].keys())

Several fields: pass the list through add_param

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # add_param applies no type check, and fetch expands the list into repeated keys.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .add_param('only[BASE][]', ['title', 'url', 'price']) \
        .fetch()
    print(result['entry'].keys())
except Exception as error:
    print('Request failed:', error)

Error handling: a list raises at the call site

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .only(['title', 'url']) \
        .fetch()
except KeyError as error:
    # Fires on only itself, because the method accepts a string and nothing else.
    print('Pass one field UID as a string:', error)

Edge case: a null field UID selects everything

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

selected_field = None

try:
    # only records nothing here, so the response carries every field.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .only(selected_field) \
        .fetch()
    print('fields returned:', len(result['entry']))
except Exception as error:
    print('Request failed:', error)

param adds an arbitrary query parameter to the request.

The same entry, for chaining.

Validation

• The check is a compound condition, so it rejects less than it looks like it does. param raises ValueError with the message "Invalid key or value arguments. Provide valid values and try again." only when one argument is None and the key is not a string.
• param(None, 'true') raises. The key is None, which fails the string test as well.
• param('locale', None) does not raise. The key is a string, so the compound condition is false, and param converts the value with str and records the text None.
• param(42, 'true') does not raise either. Neither argument is None, so param never tests the type of the key, and the request carries 42=true.
• An empty string passes every check, so param('', '') records a parameter with no name.
• Omitting either argument raises TypeError immediately, because both are positional parameters with no default.
• Any remaining errors come from the fetch() call that follows, not from param().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, an unrecognized parameter name) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. param records the pair in the entry's own parameter dictionary and makes no request.
• Converts every non-string value with str before recording it, so param('version', 4) sends version=4 and param('include_count', True) sends include_count=True with a capital letter rather than the lowercase JSON literal.
• Shares one namespace with version, include_fallback, include_branch, and include_embedded_items, so whichever call comes last wins between them.
• Loses to the inherited methods on a key collision, whatever order you called them in, because fetch merges the inherited dictionary last. See Two parameter stores on the Entry class page.
• Use param to reach a Delivery API query parameter the SDK exposes no method for. Prefer the dedicated method when one exists, because it documents the intent.
• The SDK encodes the parameters before sending them, so a value holding a space or an ampersand needs no encoding from you.
• Compare it against the add_param method, which writes to the other store and applies no string conversion.

Example

Basic usage: send a query parameter the SDK has no method for

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .param('include_dimension', 'true') \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry']['hero_image'].get('dimension'))

All parameters: both arguments, with a non-string value

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # param converts 4 to the string '4' before recording it.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .remove_environment() \
        .param('version', 4) \
        .fetch()
    print('version:', result['entry']['_version'])
except Exception as error:
    print('Request failed:', error)

Error handling: a null key raises at the call site

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

user_supplied_key = None

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .param(user_supplied_key, 'true') \
        .fetch()
except ValueError as error:
    # Fires on param itself, before any request goes out.
    print('Invalid query parameter:', error)

Edge case: a null value passes the check and reaches the request as text

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

user_supplied_value = None

try:
    # The key is a string, so the check passes and the request carries locale=None.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .param('locale', user_supplied_value) \
        .fetch()
    if 'error' in result:
        print('code:', result.get('error_code'))
except Exception as error:
    print('Request failed:', error)

remove_environment deletes the environment header from the request.

The same entry, for chaining.

Validation

• There is no client-side validation and nothing to reject. remove_environment checks whether the header key exists and skips the delete when it does not, so calling it twice cannot fail.
• Errors that do occur come from the fetch() call that follows, not from remove_environment().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection, which is the likely outcome of a request carrying no environment, returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. remove_environment deletes one header key and makes no request.
• The headers belong to the Stack, so the delete applies to every later request through that Stack until an environment call writes the header again. See The environment travels in the request headers on the Entry class page.
• fetch adds the environment query parameter only when the header exists, so after this call the request carries no environment in either place.
• This is the only route to a request without an environment. Stack raises PermissionError when its environment argument is None or empty, so the header always exists until you delete it.
• Pair it with version. The SDK documents that a request for a specific version should carry no environment, and this method is what removes it.

Example

Basic usage: send the request without an environment

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .remove_environment() \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry']['title'])

Requesting a specific version: drop the environment first

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # The SDK documents that a version request should carry no environment.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .remove_environment() \
        .version(4) \
        .fetch()
    print('version:', result['entry']['_version'])
except Exception as error:
    print('Request failed:', error)

Edge case: the delete outlives the entry that made it

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    first = stack.content_type('products').entry('<ENTRY_UID>').remove_environment().fetch()

    # This entry also sends no environment, because the header is gone from the Stack.
    second = stack.content_type('products').entry('<OTHER_ENTRY_UID>').fetch()

    # Chain environment to put it back.
    third = stack.content_type('products') \
        .entry('<OTHER_ENTRY_UID>') \
        .environment('production') \
        .fetch()
except Exception as error:
    print('Request failed:', error)

variants moves from the entry to a Variants object scoped to that entry.

A query object scoped to the variants of this entry.

Validation

• There is no client-side validation. variants passes all three arguments straight into the Variants constructor, which stores them without a type check or a null check.
• Passing None as variant_uid raises nothing here and sends no variant header later, because the header logic tests for str and list and skips anything else.
• Passing a non-dictionary as params raises nothing here. The Variants constructor stores the value as it stands. The failure appears later, as a TypeError from the urlencode call inside Variants.fetch, carrying the message "not a valid non-string sequence or mapping object".
• Omitting variant_uid raises TypeError immediately, because it is a positional parameter with no default.
• Errors that do occur come from the fetch() call on the returned object, not from variants().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, a variant UID that names no variant) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. variants constructs a new object and makes no request. Call fetch() on the result to send it.
• Returns a Variants, not an Entry, so the chain ends here. The methods on this page are unavailable on the returned object.
• Carries over the content type UID, the entry UID, and the logger from this instance. It does not carry over anything you chained beforehand, because Variants starts with empty parameter dictionaries seeded only from params.
• Sends the variant UIDs in the x-cs-variant-uid header. A list joins with commas, and a string travels as it stands.
• Sends branch as the branch header for the duration of that request, then restores whatever the Stack header held before. It also deletes the variant header afterwards, so the Stack returns to its earlier state.
• Variants.fetch() calls GET /content_types/{content_type_uid}/entries/{entry_uid} with those headers. Variants.find() calls the collection path instead, and reaches every entry of the content type rather than this one.
• Variants.fetch() raises ValueError with the message "Missing entry UID. Provide a valid UID and try again." when the entry UID is absent. That cannot happen through this method, because the factory already rejected a null entry UID.

Limitations

• Does not accept the modifiers you chained on the entry. Pass them through the params argument instead.
• Does not add the environment to the query string. Variants.fetch serializes only what params seeded and what you pass to it.

Example

Basic usage: read one variant of an entry

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .variants('<VARIANT_UID>') \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print(result['entry']['title'])

All parameters: several variants, a branch, and seeded query parameters

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # The list joins into one x-cs-variant-uid header value.
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .variants(
            ['<VARIANT_UID_ONE>', '<VARIANT_UID_TWO>'],
            branch='development',
            params={'locale': 'fr-fr', 'include_fallback': 'true'},
        ) \
        .fetch()
    print(result['entry']['locale'])
except Exception as error:
    print('Request failed:', error)

Edge case: chained modifiers do not travel to the variant request

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # locale('fr-fr') is discarded here, because Variants starts with empty parameters.
    discarded = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .locale('fr-fr') \
        .variants('<VARIANT_UID>') \
        .fetch()

    # Pass the same modifier through params instead.
    applied = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .variants('<VARIANT_UID>', params={'locale': 'fr-fr'}) \
        .fetch()
except Exception as error:
    print('Request failed:', error)

version requests a specific version of the entry instead of the latest one.

The same entry, for chaining.

Validation

• Passing None raises KeyError with the message "Invalid version. Provide a valid version and try again." A null version would reach the query string as the text None.
• Nothing else fails a check. A negative integer, a float, a string, or a version number the entry never had reaches the query string as given.
• Omitting the argument raises TypeError immediately, because version is a positional parameter with no default.
• Errors that do occur come from the fetch() call that follows, not from version().
  • fetch() raises an exception only for network failures (timeout, DNS error, dropped connection).
  • An API-level rejection (for example, a version number the entry never had) returns as a normal result with an error key. It does not raise an exception.
  • Check the result for an error key even inside a try block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

• Client-side only. version records the number in the entry's own parameter dictionary and makes no request. fetch sends it on that call.
• Omitting version returns the latest published version of the entry.
• Calling version twice replaces the first number. The SDK stores it under a single key.
• The SDK documents that a version request should carry no environment, and fetch copies the environment header into the query string whenever that header exists. Stack requires an environment at construction, so chain the remove_environment method before fetch to send the version without one.
• version writes to the entry's own store, so add_param with the key version overrides it. See Two parameter stores on the Entry class page.

Example

Basic usage: read version 4 of an entry

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .version(4) \
        .fetch()
except Exception as error:
    # Raised only for network failures (timeout, DNS error, dropped connection)
    print('Request failed:', error)
else:
    if 'error' in result:
        # The Delivery API rejected the request and returned the error body
        print('Delivery API error:', result['error'])
    else:
        print('version:', result['entry']['_version'])

Version without an environment: the combination the SDK documents

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .remove_environment() \
        .version(2) \
        .fetch()
    print('title at version 2:', result['entry']['title'])
except Exception as error:
    print('Request failed:', error)

Error handling: a null version raises at the call site

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

requested_version = None

try:
    result = stack.content_type('products') \
        .entry('<ENTRY_UID>') \
        .version(requested_version) \
        .fetch()
except KeyError as error:
    # Fires on version itself, before any request goes out.
    print('Invalid version:', error)

Edge case: a negative version reaches the query string unchecked

import contentstack

stack = contentstack.Stack('<API_KEY>', '<DELIVERY_TOKEN>', '<ENVIRONMENT>')

try:
    # The SDK sends version=-1 and lets the Delivery API answer.
    result = stack.content_type('products').entry('<ENTRY_UID>').version(-1).fetch()
    if 'error' in result:
        print('code:', result.get('error_code'))
except Exception as error:
    print('Request failed:', error)