Surface Content Generation

Overview

Surface content generation allows you to create channel-specific versions of product content that are automatically optimized for each platform’s requirements. Instead of manually editing titles for Google Shopping character limits or rewriting descriptions for mobile screens, the AI adapts the content based on surface constraints you define.

Prerequisites

A workspace with at least one catalog and products
API key with write:surfaces scope (for API usage)
At least one surface available (system surfaces are always available)

Generate via Canvas

The simplest way to generate surface-adapted content is through the Canvas UI:

Open Canvas for a product

Navigate to your catalog, find the product, and open its Canvas.

Select a surface

Use the surface selector dropdown at the top of the Canvas. Choose from system surfaces (Google Shopping, OpenAI Commerce, etc.) or any custom surfaces your workspace has configured.

Generate content

Click any Canvas action (Text, SEO, etc.). The AI applies the surface constraints automatically — titles will respect the max length, tone will match the surface requirements, and format hints guide the output.

Review and commit

Review the generated content in the surface preview. When satisfied, commit the content. It is stored as a surface override for this product.

Content is now available

The override is immediately available to all channels. The next Canal 1 feed sync, Canal 2 search result, or Canal 3 tool call for this product + surface will return the adapted content.

Generate via API

Step 1: List available surfaces

curl "https://app.alana.shopping/api/workspace/{workspaceId}/surfaces" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "surfaces": [
    {
      "id": "...",
      "surface_key": "google_shopping",
      "display_name": "Google Shopping",
      "is_system": true,
      "constraints": {
        "max_title_length": 150,
        "max_description_length": 5000,
        "tone": "seo-optimized"
      }
    }
  ]
}

Step 2: Generate content with surface constraints

Trigger Canvas generation with a surfaceKey parameter:

curl -X POST "https://app.alana.shopping/api/ai/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "BRAND_ID",
    "productId": "PRODUCT_ID",
    "type": "text",
    "surfaceKey": "google_shopping"
  }'

Step 3: Read the resolved product

curl "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "product": {
    "productId": "...",
    "surface_key": "google_shopping",
    "resolved": {
      "title": "Organic Linen Blazer - Navy | Sustainable Premium",
      "description": "Premium organic linen blazer in navy..."
    },
    "overrides": {
      "title": "Organic Linen Blazer - Navy | Sustainable Premium",
      "description": "Premium organic linen blazer in navy..."
    },
    "cached": true
  }
}

Step 4: Set overrides manually (optional)

Skip AI generation and set overrides directly:

curl -X PUT "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "overrides": {
      "title": "My custom Google Shopping title",
      "description": "My custom description for Google"
    }
  }'

Serve via Channels

Canal 1 — Feed API

Surface overrides are applied automatically when the platform maps to a surface:

GET https://app.alana.shopping/api/mcp/feed/google_shopping?workspace_id={workspaceId}&catalog_id={catalogId}

Products with google_shopping overrides will return the adapted title and description. Products without overrides return the universal content.

Canal 2 — Search API

GET https://app.alana.shopping/api/mcp/search?workspace_id={workspaceId}&surface=google_shopping&q=blazer

All products in the result set will have surface resolution applied. The surface parameter accepts any valid surface key.

Canal 3 — MCP Tools

{
  "tool": "get_product",
  "params": {
    "product_id": "PRODUCT_ID",
    "workspace_id": "WORKSPACE_ID",
    "surface": "agent_response"
  }
}

Or use the dedicated surface tools:

{
  "tool": "list_surfaces",
  "params": { "workspace_id": "WORKSPACE_ID" }
}

{
  "tool": "get_surface_product",
  "params": {
    "product_id": "PRODUCT_ID",
    "workspace_id": "WORKSPACE_ID",
    "surface_key": "agent_response"
  }
}

Create Custom Surfaces

curl -X POST "https://app.alana.shopping/api/workspace/{workspaceId}/surfaces" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "surface_key": "tiktok_shop",
    "display_name": "TikTok Shop",
    "constraints": {
      "max_title_length": 34,
      "max_description_length": 200,
      "tone": "casual",
      "format_hints": "Short punchy sentences. Use emojis sparingly. Focus on trend appeal."
    }
  }'

The surface_key must match ^[a-z][a-z0-9_]{1,48}[a-z0-9]$. It cannot be changed after creation.

Delete a Surface Override

To revert a product back to universal content for a surface:

curl -X DELETE "https://app.alana.shopping/api/workspace/{workspaceId}/products/{productId}/surfaces/google_shopping" \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Start with system surfaces for standard platforms (Google Shopping, OpenAI Commerce). They are pre-configured with optimal constraints.
Use Canvas for generation rather than setting overrides manually — the AI produces better results when it understands the surface constraints during generation.
Create custom surfaces sparingly — each new surface adds content generation and storage overhead per product. Only create surfaces you’ll actively generate overrides for.
Review before publishing — generated surface content should be reviewed, especially for tone and accuracy, before relying on it in production channels.
Cache warm-up — after creating a surface or updating constraints, the cache warmer runs automatically for the top 100 products. New products are warmed on first access.

Getting Started

Core Concepts

Guides

Overview

Prerequisites

Generate via Canvas

Generate via API

Step 1: List available surfaces

Step 2: Generate content with surface constraints

Step 3: Read the resolved product

Step 4: Set overrides manually (optional)

Serve via Channels

Canal 1 — Feed API

Canal 2 — Search API

Canal 3 — MCP Tools

Create Custom Surfaces

Delete a Surface Override

Best Practices

​Overview

​Prerequisites

​Generate via Canvas

​Generate via API

​Step 1: List available surfaces

​Step 2: Generate content with surface constraints

​Step 3: Read the resolved product

​Step 4: Set overrides manually (optional)

​Serve via Channels

​Canal 1 — Feed API

​Canal 2 — Search API

​Canal 3 — MCP Tools

​Create Custom Surfaces

​Delete a Surface Override

​Best Practices

Overview

Prerequisites

Generate via Canvas

Generate via API

Step 1: List available surfaces

Step 2: Generate content with surface constraints

Step 3: Read the resolved product

Step 4: Set overrides manually (optional)

Serve via Channels

Canal 1 — Feed API

Canal 2 — Search API

Canal 3 — MCP Tools

Create Custom Surfaces

Delete a Surface Override

Best Practices