Moderation Templates

Moderation templates are reusable, client-owned sets of content and image rules. Build and publish a template before selecting it during catalogue creation.

All template requests are server-to-server calls authenticated with x-client-key. Inputs and responses contain customer-safe rule configuration only; runtime prompts, engine parameters, tenant identifiers, and infrastructure fields are never exposed.

Template lifecycle

Create a draft template.
Add and edit its content and image rules.
Publish the completed revision.
Select the published template with moderationTemplateId when creating a catalogue.
Clone a published or archived template when you need an editable revision.
Archive a template that should no longer be selected for new catalogues.

Only drafts are mutable. Published and archived templates are immutable. Archive is idempotent, and there is no top-level template delete route.

Template routes

The base path is /api/v1/admin/moderation/templates.

Method	Relative path	Purpose
`GET`	`/`	List your templates; optionally filter by lifecycle status
`POST`	`/`	Create a draft template
`GET`	`/{templateId}`	Get a template and its ordered rules
`PATCH`	`/{templateId}`	Update draft metadata
`POST`	`/{templateId}/clone`	Create a new draft from a template
`POST`	`/{templateId}/publish`	Publish an immutable revision
`POST`	`/{templateId}/archive`	Archive a template

Create a draft:

curl -X POST https://platform.youzu.ai/api/v1/admin/moderation/templates \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketplace quality",
    "version": "2026.07",
    "description": "Content and image standards for marketplace listings",
    "isDefault": false
  }'

Clone requests provide the metadata for the new draft, including a new name and version. Publishing can optionally make the revision your default. Archiving does not require a request body.

Content and image rules

Each child collection supports list, create, detail, update, and delete while its parent is a draft:

Method	Relative path
`GET`, `POST`	`/{templateId}/content-rules`
`GET`, `PATCH`, `DELETE`	`/{templateId}/content-rules/{ruleId}`
`GET`, `POST`	`/{templateId}/image-rules`
`GET`, `PATCH`, `DELETE`	`/{templateId}/image-rules/{ruleId}`

A customer-safe child rule uses this shape:

{
  "ruleType": "image-background-quality",
  "severity": "medium",
  "enabled": true,
  "sortOrder": 20,
  "configuration": {
    "label": "Clean product background",
    "description": "Flag distracting or unsuitable product-image backgrounds",
    "appliesTo": "all_images",
    "unpublishOnViolation": false,
    "approvalFeedbackMessage": "Confirm that the background is acceptable"
  }
}

appliesTo is relevant to image rules and can target the first image or all images. Rule order is controlled by sortOrder.

Template reference images

An image-rule configuration can contain ordered referenceImages with an allowed or disallowed role and an optional caption. Upload each image to Youzu-managed storage before adding it to a rule.

1. Request upload credentials

curl -X POST https://platform.youzu.ai/api/v1/admin/upload/signed \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"acceptable-background.webp"}'

The response contains a storage key, a short-lived uploadUrl and authorizationToken, the canonical cdnUrl, and an expiresAt timestamp:

{
  "key": "4cfe61ba-7319-45e8-b272-2a5c291bb7a0.webp",
  "uploadUrl": "https://storage.example/upload/...",
  "authorizationToken": "SHORT_LIVED_UPLOAD_TOKEN",
  "cdnUrl": "https://cdn.example/file/youzu/4cfe61ba-7319-45e8-b272-2a5c291bb7a0.webp",
  "expiresAt": 1784894700000
}

Treat the upload URL and authorization token as credentials: do not log, persist, or send them to untrusted clients.

2. Upload the image bytes

Send the file to the returned uploadUrl. For the native upload response shown above, use the returned values in these headers:

curl -X POST "UPLOAD_URL" \
  -H "Authorization: SHORT_LIVED_UPLOAD_TOKEN" \
  -H "X-Bz-File-Name: STORAGE_KEY" \
  -H "Content-Type: image/webp" \
  -H "X-Bz-Content-Sha1: do_not_verify" \
  --data-binary @acceptable-background.webp

3. Attach the managed asset to an image rule

Use the response key as storageKey. assetUrl is optional; when supplied, it must exactly match the returned cdnUrl.

{
  "ruleType": "image-background-quality",
  "configuration": {
    "referenceImages": [
      {
        "storageKey": "4cfe61ba-7319-45e8-b272-2a5c291bb7a0.webp",
        "assetUrl": "https://cdn.example/file/youzu/4cfe61ba-7319-45e8-b272-2a5c291bb7a0.webp",
        "role": "allowed",
        "caption": "Example of an acceptable clean background",
        "mimeType": "image/webp",
        "sortOrder": 0
      }
    ]
  }
}

Reference images must be valid, decodable JPEG, PNG, or WebP files no larger than 25 MiB. A configuration can contain at most 50 references. role and a non-negative sortOrder are required; caption is optional and limited to 1,000 characters. Youzu verifies the stored bytes, signature, canonical storage key, managed URL, media type, and size. Arbitrary external URLs are rejected.

Reference examples become part of the immutable published revision. To change them after publication, clone the template, edit the draft, and publish the new revision.

Apply a template

Supply a published template when creating a catalogue:

{
  "name": "Home Collection",
  "languages": ["en"],
  "moderationTemplateId": "9aac11a8-e55b-491b-a8f9-11f3ac9aab20"
}

Youzu verifies that the template is published and owned by the authenticated client. The public API does not provide a route to apply a template to an existing catalogue.

Manual Dashboard Upload

Product Moderation