HomeDev guideAPI ReferenceGraphQL
Dev guideUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

CMP Content Repository

Describes the Optimizely Content Marketing Platform Content Repository structure.

A Content Repository is a system that stores and hosts content and defines the structure of content.

You determine how the content is finally delivered to the consumer and let customers choose the media of their choice.

Content Repository is like a decoupled (or headless) CMS with the following added benefits:

  • Stored content with metadata that is accessible by an API
  • A workflow for creating content production
  • Integrated campaign planning
  • Integrated content from Optimizely Digital Asset Management (DAM) with collections for distribution of content
  • Integration with CRM and marketing automation to analyze content with ROI
  • Infrastructure to publish and distribute content
  • A preview for marketers while keeping the flexibility of not imposing it on the users of structured content. The preview is dynamically created which is especially useful for legal approval.

Entities in the Asset Service

The Asset Service indexes content assets for previewing, searching and listing structured content. Assets are made from the following entities:

  • An instance is an organization or creative management platform.
  • A Content Type is the definition of a structured content. Content is an instance of a content type.
  • Structured content is content that contains fields that define the metadata of the content. When you create structured content in the Assets Service, you can change the content directly and independently in the Content Repository. Changed data is re-indexed.
  • A field can be a single value or an ordered list of values. You can specify default values for fields (except the Content Type reference).

The Instance, Content Type and Content entities have the following fields associated with them:

  • Instance – (also known as Organization, CMP Instance)
    • Instance GUID
    • Name
  • Content Type – (also known as Content Blueprint, Content Model, Content Schema, Content Template)
    • Name
    • Source – Optional. Denotes source of where the content type originates. If source is set, those content types are not editable from within CMS to support content types being controlled by other systems. For example, AEM, Sitecore or CMP's predefined content types.
    • Source ID – Optional. Denotes the ID of the content type from which it is being imported.
    • Source Metadata – Freeform text field to store any meta-data to be used by downstream system.
    • Instance GUID – Foreign key to Instance.
    • Thumbnail GUID – GUID of the thumbnail in file server; similar to how attachment and asset upload works. This can represent what the content type could look like.
    • Content Type GUID – Must be unique across all content types because it is used in reference.
    • Is Component? – Boolean that controls whether to list this content type in structured content creation in the Task & Content tab and whether you can add the template. You should not add templates to Components. With this prototype, you cannot create a component from a task because when a component is created from Task, it does not show up in the library. However, when a component is embedded in a non-component content type, the component gets an embedded behavior experience in the task's structured content editor.
    • Is Disabled? – Boolean that controls whether the content type is retired. A content type is not deleted because of the complexity of contents created and used from a content type. When disabled, the content type is not listed for editing or creation of content.
    • Versions[] – Ordered list of versions.
      • Version GUID – Generated GUID.
      • Create At
      • Created By – User GUID.
      • Is Latest?
      • Expected Locales – Array locale strings in the form of en_US.
      • FieldDefinitions
        • Name
        • Source ID – Optional. Denotes the ID of the field from which it is being imported.
      • Source Metadata – Freeform text field to store any meta-data to be used by downstream system.
      • Type – One of: Text, Rich Text, Number, Date & time, Location, Boolean, URL, JSON Object, Choice, Library Asset, Content Type Reference.
      • Is List – Flag to signify whether this is a list field.
      • Is required – For list, it would mean at least one item is required.
      • Needs Internationalization
    • Templates – (also known as Layout, Format) An ordered list of templates with a default blank template added at creation. The list cannot be empty.
      • Template GUID – Generated GUID.
      • Name
      • Description
      • Source ID – Optional. Denotes the ID of the template from which it is being imported.
      • Source Metadata – Freeform text field to store any meta-data to be used by downstream system.
      • HTML Template
    • Description – Note about the content type.
  • Content – (also known as Structured Content)
    • Content GUID – generated GUID
    • Title
    • Content Type GUID
    • Instance
    • Is Reusable – Especially useful for Components; as if is Private is false; it can be used as Shared Component and can be referred to by other Content.
    • Is Expired? – Gives delete-like capability for a content in Content Repository. Structured Content can be deleted from the library, but at that point it should be expired from the content repository. A CMS-only component can be expired from CMS view. All expired content is accessible in the Vault of Content Repository
    • Content Type Field Definition Version GUID – Foreign key to Content Type's Field Definition's specific Version
    • Template – The link to one of the templates in a content type
    • Versions – Ordered list of versions
      • Field Version GUID – Generated GUID
      • Name – Optional. Name a content to create a milestone around creation of a content; for example, session end milestone in case of auto-save.
      • Create At
      • Created By – User GUID
      • Generated Previews: Dict(Preview name: str, (GCP Mime-Type, GCP Content Data)) – Preview generated for content's specific version via API
      • Is Latest?
      • Dict (key, Dict(Locale, FieldValue[]) – Array of values keyed against locale and then by field key. Locale will always default to system default of en_US. Must match its Type (see more on this below). If list size is 1, that means it is a single value rather than a list.



Content Repository versions field definitions in a content type and field values in a structured content. Each version is unique and cannot be changed.

Field types for the back end

You can configure a field to be required or optional, list or singular, or needing internationalization.

  • Text Field – Supports minimum and maximum length configuration and can add a pattern to validate the string against.
  • Rich Text Field – Not supported in Content Repository. However, Contentful supports this field to let Quill and TinyMCE features to be configured. For example, headings h1 and h2 are not allowed, but h3 and h4 are allowed, and embedding images is allowed or not allowed and so on.
  • Boolean
  • Datetime – Minimum date and maximum date (configurable).
  • Number – Minimum number and maximum number (configurable).
  • Library Asset – values: article , image , video , raw_file , structured_content

You can configure the type of asset and select multiple types. For example, a field can specify that a field can have image or video as its value.

  • Content Type Reference – Specify one or more types of content to embed or link.
    • You can configure embed-only to be reused. If you allow reuse from the content type, you should be able to mark it as one-time in the task details of the page so the content cannot be reused.
    • You can configure link-only to enable embedded edit.
  • Choice – values: Display option , Tag , Radio , Dropdown. Options are defined as part of the type.
  • URL
  • Location
  • JSON – Provides flexibility to submit random values to be used by downstream systems.



Media (Image, Video) is intentionally left out because it creates confusion between which image ends up in the library versus in the CMS. For the Library Asset type field, you can upload an image, video or file, which you can automatically add back to the task.

Core field definitions

Every field definition has the following common attributes (regardless of its type).

  • key – Required. A unique key for identifying the field.
  • name – Required. Name of the field.
  • is_required – Required. Whether the field is required.
  • need_internationalization – Required. Determines the need for internationalization. (This is not used for now.)
  • is_list – Required. Specifies single value or multiple values.
  • min_list_length – Optional. If multiple, specify minimum number of values.
  • max_list_length – Optional. If multiple, specify maximum number of values.
  • field_type – Optional. Enter name of the field.
  • order_index – Optional. Field's order index; see Ordering fields.
  • source_id – Optional. Source ID; see External content types.
  • source_metadata – Optional. Source metadata; see External content types.
  • editor_metadata – Optional. Field editor metadata; see Field editor metadata.
  • help_text – Optional. An informatory help text that describes the field.

Ordering fields

You can control the order in which fields are rendered when content is being created using the order_index attribute. If you do not specify some fields in order_index , those fields are rendered in an unpredictable order, followed by the fields that are specified in ascending order.

The order_index attribute is available in content type and FieldValue to retain the order in which values are entered in the list field.

Field Editor Metadata

You can customize the field value editor in the following ways:

  • integer versus decimal for Number Field
  • Date Only instead of Date Time
  • Date/format to be used in the datetime editor (that is, mm/dd/yyyy versus dd/mm/yyyy or AM/PM versus 24-hr time format)

Web page content type

A system content type called Web page has the following common fields:

  • SEO keywords
  • SEO metadata
  • URL slug
  • Analytics pixel – In the task details page, it automatically detects locales as they are added and generates a pixel that is unique per locale. You cannot edit the pixel.

Any other content type that wants these common fields can directly associate them.


You can create structured content from the Task Details page such that a single Asset contains multiple locales. However, each locale-specific article is published independently. Statistics are gathered independently and each shows in the library independently (with lineage). For example, if Article A is published in American English (en), French (fr) and Swedish (sv), there are three separate assets: Article_A_en, Article_A_fr and Article_A_sv.

Changes that trigger events from the Content Repository

  • Content Type
    • Content Type created
    • Content Type core info updated
    • Content Type version created
    • Content Type disabled
  • Structured Content
    • Content created
    • Content core info updated
    • Content version created
    • Content expired
    • Content effected
    • Preview requested
    • Preview generation started
    • Preview completed (value: complete, error, timeout)
    • Preview available

Most events are straightforward, but Content effected may have a shared component with other content. For example, shared component A could be part of structured content B and structured content C. If shared component A is changed, the Content Repository identifies the change to the initial component and then each affected component.

Permissions for content

Role-based permissions determine whether you can create, update or delete a component. Structured content inherits permission from the asset.

Integrate CMP Content Repository with CMS

You can use the API to create a content type and template, but you cannot modify these content types to avoid conflict and merge issues. External systems (such as SDL Tridion or AEM) can create their own content types and use them in CMP. The Source metadata and Source ID fields are set when the content type is created (you cannot update it afterward); the fields identify the content type as coming from external sources. Application users can view the definition and structure, and can create content from the external content type, and Source ID and Source metadata are available as optional fields at Field Definition and Template, which takes advantage of storing native CMS fields and template identifiers and additional freeform metadata.

Source metadata is also available at the content type level, which you can update after it is created. The Source metadata receives any string, has no format limitation, and the system populating them can control the metadata.


  • GET Instances
  • PUT to create/register a new Instance
  • GET Content Types in context to an Instance; stretch goal – with filtering on Component
  • POST to Content Types to create new content in context to an Instance
  • GET a Content Type with latest version in full
  • GET a Content Type with latest version in full and expanded recursively for preview context
  • GET Content Type versions
  • GET a Content Type version
  • POST to a Content Type to update its core information
  • POST to Content Type versions to create a new field definition version
  • GET Contents in context to an Instance filtered by Content Type, Component, Private Type and Content's title (full text) paginated
  • POST to Contents to create new content
  • GET a Content with its latest version
  • GET a Content version
  • GET a specific Version of a Content
  • GET a Content with all of its nested content for preview context
  • GET a Content with all of its nested content for search indexing
  • POST to a Content to update its core information
  • POST to a Content's Versions to update it (Patch will be supplied later on) with a new version
  • GET a Content Type's templates resource to list all the templates for a content type
  • POST to a Content Type's templates resource to add a template to the content type
  • GET a Content Type's specific template (retrieves it)
  • PUT to a Content Type's template (updates it)
  • DELETE to a Content Type's Template (DELETES it)
  • Since listing of structured content will be limited to Assets for MVP, we will not have the delete endpoints. All these endpoints will be prefixed with v0 to allow for versioning of the Content Repository API.

Common HTTP response status codes across the endpoints:

  • 200 - For requests to GET endpoints
  • 201 - If your content was successfully created for you POST request, the API returns the URI with the Location of the created content or content type
  • 202 - If your content type or content was successfully updated for you PUT request
  • 404 - If there was no content type or content found in the referenced URI
  • 412 - Entity Tag supplied for PUT requests are not valid
  • 422 - If input JSON does not meet validation criteria
  • 500 - For any unexpected, back-end error from Content Repository