Get started with Optimizely Mark tools
Mark (Optimizely Agent Platform) offers AI-powered content management tools for CMS 13 (PaaS) sites. Use these tools to create and edit AI-driven content, improve Search Engine Optimization (SEO), and generate schema markup within the CMS editorial interface.
Prerequisites
- .NET 10.0 or later.
- EPiServer.Cms.Core 13.x (Optimizely CMS 13).
- Optimizely.Opal.Tools 13.1.0 or later.
- Opti ID configured for your CMS instance.
Install the NuGet package
Install the NuGet package.
dotnet add package Optimizely.Cms.Opal.ToolsConfigure services and endpoints
Register services
Add the CMS Mark tools to your service collection in Startup.cs or Program.cs.
services.AddCmsOpalTools();This registers the Mark tool service and all CMS tools in a single call. The underlying services (for example, IContentService and ISeoService) register automatically with Optimizely's [ServiceConfiguration] attribute and require no manual configuration.
Configure endpoints
Map the tool discovery and execution endpoints in your application pipeline.
app.UseEndpoints(endpoints =>
{
endpoints.MapContent();
endpoints.MapOpalTools("/opal/");
});The MapOpalTools method accepts a prefix parameter (for example, "/opal/") that determines the base path for all tool endpoints.
- GET {prefix}discovery – Tool discovery endpoint (for example, /opal/discovery).
- POST {prefix}{tool_name} – Tool execution endpoints (for example, /opal/paas_cms_list_content_types).
Configure Mark instance
Register your tool endpoints with the Mark backend so Mark can discover and invoke them.
- Go to the Mark instance admin portal (for example, https://mark.optimizely.com/instances/YOUR_INSTANCE_ID)
- Add a new Tool Registry entry.
- Set the discovery URL to your application's discovery endpoint.
https://YOUR_CMS_HOST/opal/discoveryThe Mark backend calls this URL to retrieve the list of available tools and their parameter schemas.
Authenticate users with Opti ID
All tools require authentication with Opti ID. When a user interacts with the Mark chat widget in the CMS UI, authentication flow is as follows:
- The user authenticates with Opti ID when logging in to CMS.
- Mark chat passes the user's Opti ID token to the Mark backend.
- The Mark backend forwards the token when it invokes tool endpoints.
- Each tool validates the token and impersonates the authenticated user for all CMS API calls.
The authentication flow ensures all content operations respect each user's CMS permissions. Each user can only read, create, edit, or delete content they have permission to access.
Available tools
Category | Tool name | Description |
|---|---|---|
Content Types | paas_cms_list_content_types | List all available content types. |
Content Types | paas_cms_get_content_type_details | Get detailed information about a content type. |
Content Types | paas_cms_create_content_type | Create a new content type. |
Content Types | paas_cms_update_content_type | Update an existing content type. |
Content Types | paas_cms_delete_content_type | Delete a content type. |
Property Groups | paas_cms_list_property_groups | List property groups (tabs). |
Property Groups | paas_cms_create_property_group | Create a new property group. |
Content Items | paas_cms_get_content_data | Get content item data and properties. |
Content Items | paas_cms_update_content_item | Update content item properties or create a new content item (draft). |
Content Items | paas_cms_delete_content_item | Move content to the waste basket. |
Content Items | paas_cms_publish_content_item | Publish a content item. |
Variations | paas_cms_create_content_variation | Create a locale variation of content. |
Preview | paas_cms_get_content_preview_url | Get the preview URL for content. |
Search Engine Optimization (SEO) | paas_cms_seo_analysis | AI-powered SEO analysis of content. |
Search Engine Optimization (SEO) | paas_cms_seo_edit | Apply SEO recommendations to content. |
Generative Engine Optimization (GEO) | paas_cms_geo_analysis | AI-powered generative engine optimization analysis. |
Generative Engine Optimization (GEO) | paas_cms_geo_apply | Apply JSON-LD schema markup to content. |
Display Templates | paas_cms_list_display_templates | List all display templates. |
Display Templates | paas_cms_get_display_template | Get one or more display templates by key. |
Display Templates | paas_cms_create_display_template | Create a display template (Visual Builder style or layout). |
Display Templates | paas_cms_update_display_template | Update an existing display template. |
Media | paas_cms_upload_media | Upload a media asset into CMS. |
Endpoints
When you configure MapOpalTools("/opal/"), the package exposes the following:
Method | Path | Description |
|---|---|---|
GET | /opal/discovery | Returns the tool registry and lists all available tools with their parameter schemas. |
POST | /opal/{tool_name} | Executes a specific tool (for example, /opal/paas_cms_list_content_types). |
Local development
See the samples/OptiAlloy directory for a working sample site. To run it locally, complete the following:
- Start a SQL Server in Docker.
docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=Qweerty123" -p 1433:1433 --name ms_sql_server -d mcr.microsoft.com/mssql/server:2022-latest- Create the database.
docker exec ms_sql_server /opt/mssql-tools18/bin/sqlcmd -S localhost -U SA -P Qweerty123 -C -Q "CREATE DATABASE OptiAlloyOpal"- Set the connection string using user secrets.
dotnet user-secrets set "ConnectionStrings:EPiServerDB" "Server=localhost,1433;Database=OptiAlloyOpal;User Id=SA;Password=Qweerty123;Encrypt=false;TrustServerCertificate=true;Connect Timeout=30" --project samples/OptiAlloy/OptiAlloy.csproj- Run the sample site.
dotnet run --project samples/OptiAlloy/OptiAlloy.csprojThe site runs at https://localhost:5000. Verify tools are registered by going to https://localhost:5000/opal/discovery.