Product Moderation

Catalogue moderation lets you define versioned rules, activate an exact ruleset, review flagged products, and use false-positive feedback to refine future rules.

All routes use x-client-key and are scoped to the catalogue in the URL. Youzu derives the client from the key and rejects access to another client's catalogue.

Moderation workflow

Create a draft ruleset or clone an existing ruleset.
Add and test content or image rules.
Preview activation impact and resolve blockers.
Activate the exact draft revision.
Review flagged products and approve or reject the result.
Accept useful false-positive feedback to generate a new draft refinement.

Ruleset routes

The base path is /api/v1/admin/catalogue/{catalogueId}/moderation.

Method	Relative path	Purpose
`GET`, `POST`	`/rulesets`	List rulesets or create a draft
`GET`, `PATCH`	`/rulesets/{rulesetId}`	Get a ruleset or update draft metadata
`POST`	`/rulesets/{rulesetId}/clone`	Clone a ruleset into a new draft
`GET`	`/rulesets/{rulesetId}/activation-impact`	Preview selected products, work, and blockers
`POST`	`/rulesets/{rulesetId}/activate`	Activate the exact ruleset revision
`GET`	`/rulesets/{rulesetId}/labels`	Resolve customer-facing labels for rule slugs
`POST`	`/rulesets/{rulesetId}/rules`	Add a rule to a draft
`PATCH`, `DELETE`	`/rulesets/{rulesetId}/rules/{slug}`	Revise or remove a draft rule
`POST`	`/rulesets/{rulesetId}/rules/{slug}/reference-images`	Upload a reference image
`DELETE`	`/rulesets/{rulesetId}/rules/{slug}/reference-images/{assetId}`	Remove a reference image
`POST`	`/rulesets/{rulesetId}/rules/{slug}/regression-test`	Run customer-facing rule checks

Define a rule

Rules expose only the settings a customer can safely control:

Field	Description
`title`, `description`	Human-readable rule intent
`severity`	`high`, `medium`, or `low`
`imageScope`	`NONE`, `FIRST_IMAGE`, or `ALL_IMAGES`
`enabled`	Whether the rule participates in moderation
`sortOrder`	Stable evaluation and display order
`unpublishOnViolation`	Whether a violation can suppress affected offers
`approvalFeedbackMessage`	Optional instruction shown during approval
`slug`	Optional stable identifier on create; it cannot be changed later

curl -X POST https://platform.youzu.ai/api/v1/admin/catalogue/550e8400-e29b-41d4-a716-446655440000/moderation/rulesets/4a5378a4-059c-4de8-9bfe-49211eea43ae/rules \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "No promotional text overlay",
    "description": "Flag product images containing promotional text overlays",
    "severity": "medium",
    "imageScope": "ALL_IMAGES",
    "unpublishOnViolation": false,
    "enabled": true,
    "sortOrder": 10,
    "slug": "no-promotional-overlay"
  }'

Rule changes create immutable revisions within the draft. Internal prompts, checker selection, arbitrary parameters, and grounding configuration cannot be submitted or retrieved through the customer API.

Reference images and regression checks

Upload multipart/form-data containing file, role (allowed or disallowed), and an optional caption. Files must be valid JPEG, PNG, or WebP images no larger than 25 MiB. Youzu verifies the decoded file signature instead of trusting the filename or declared media type.

Reference images and stored regression cases are evaluated by the regression-test route. Run the check after changing a rule and before activation. The customer API does not expose routes for manually creating regression cases or writing test results.

Preview and activate

Always call activation-impact before activation. It reports changed and reused rules, selected products, enforcement-only work, whether AI evaluation is needed, and blockers. Activation fails while blockers remain.

Activation makes the exact revision active and queues any required downstream product work. If queueing fails, the API can return 502 after the ruleset has already been committed as active. Fetch the ruleset before retrying so that you do not assume activation was rolled back.

Review flagged products

Review routes use the base path /api/v1/admin/catalogue/{catalogueId}/review.

Method	Relative path	Purpose
`GET`	`/queue`	List products by review state, severity, or rule slug
`GET`	`/queue/counts`	Count pending, approved, and rejected reviews
`GET`	`/results/{productId}`	Get the product's latest moderation result
`POST`	`/results/{productId}/approve`	Approve selected violations and optionally record feedback
`POST`	`/results/{productId}/reject`	Reject the moderation review
`GET`	`/feedback`	List rule-specific false-positive feedback
`POST`	`/feedback/{feedbackId}/accept`	Accept feedback and create a draft rule refinement
`POST`	`/feedback/{feedbackId}/reject`	Close feedback without refining the rule

The queue supports review_status, severity, slug, order, limit, and offset filters. Use the labels endpoint to present stable rule slugs as customer-facing names.

Approve or reject a result

Approval can identify ruleSlugs from the product's current violations and include rule-specific false-positive feedback. Youzu validates every feedback slug against those selected/current violations. An optional actor is stored as your audit label.

{
  "actor": "catalogue-quality-team",
  "ruleSlugs": ["no-promotional-overlay"],
  "feedback": [
    {
      "slug": "no-promotional-overlay",
      "text": "The text is part of the product packaging, not an overlay"
    }
  ]
}

Approving resolves the moderation holds for the selected violations. If moderation was the only reason an offer was suppressed and no blocking hold remains, Youzu can republish it; inspect the response's republished value. Rejecting confirms the moderation decision and can unpublish affected offers; inspect unpublished.

Accepting feedback does not silently change the active ruleset. It creates a draft rule refinement for review and later activation. Rejecting feedback only closes that feedback item. There is no customer-facing review rerun route; activation and the documented processing flows control subsequent evaluation.

Moderation Templates