Embedding Annotations in Your UI

Annotations map compliance issues to specific locations in content. This guide shows how to use them to highlight issues natively in your application.

Annotation Types

Text Span

For scripts, ad copy, captions, descriptions.

{
  "type": "text-span",
  "agentId": "advertising-law",
  "severity": "high",
  "message": "'Guaranteed' claim may violate FTC rules",
  "suggestion": "Consider 'may help' instead",
  "textLocation": {
    "start": 120,
    "end": 137,
    "matchedText": "guaranteed results"
  }
}

How to use:

start and end are character offsets (0-indexed) into the original content.text
Highlight matchedText in the editor with the appropriate severity color
Show message on hover/click
Show suggestion as an inline fix option

Timeline

For video content with timestamps.

{
  "type": "timeline",
  "agentId": "metadata-labeling",
  "severity": "medium",
  "message": "AI-generated segment missing disclosure label",
  "suggestion": "Add visible AI disclosure overlay",
  "timelineLocation": {
    "startMs": 15000,
    "endMs": 28000,
    "track": "video"
  }
}

How to use:

Mark the flagged time range on the video timeline
track indicates which track (video, audio, subtitle)
Show a warning marker at startMs on the timeline scrubber

Image Region

For visual content with detected elements.

{
  "type": "image-region",
  "agentId": "rights-clearance-image",
  "severity": "high",
  "message": "Possible celebrity face detected",
  "suggestion": "Obtain likeness rights or replace",
  "imageLocation": {
    "imageUrl": "https://example.com/ad.jpg",
    "boundingBox": { "x": 120, "y": 45, "width": 200, "height": 250 }
  }
}

How to use:

Draw a highlight rectangle at the bounding box coordinates
boundingBox uses pixel coordinates relative to the original image dimensions

Global

Applies to the entire content, not a specific location.

{
  "type": "global",
  "agentId": "platform-policy",
  "severity": "medium",
  "message": "YouTube requires AI disclosure toggle for AI-generated content",
  "suggestion": "Enable the AI-generated content disclosure in YouTube Studio"
}

How to use:

Show as a banner or top-level warning
Not tied to a specific content location

Severity Colors (Suggested)

Severity	Color	Usage
critical	Red (#FF3B30)	Bright red highlight, blocking banner
high	Orange (#FF9500)	Orange highlight, prominent warning
medium	Yellow (#FFCC00)	Yellow highlight, informational
low	Blue (#007AFF)	Subtle blue indicator
info	Gray (#8E8E93)	Gray text, no highlight

Grouping Annotations

For a clean UI, group annotations by:

By agent — “Advertising Law: 2 issues, Platform Policy: 1 issue”
By severity — Show critical/high first
By location — Sort text-span by start offset, timeline by startMs

Video

Other

Embedding Annotations in Your UI

Embedding Annotations in Your UI

Annotation Types

Text Span

Timeline

Image Region

Global

Severity Colors (Suggested)

Grouping Annotations

​Embedding Annotations in Your UI

​Annotation Types

​Text Span

​Timeline

​Image Region

​Global

​Severity Colors (Suggested)

​Grouping Annotations

Embedding Annotations in Your UI

Annotation Types

Text Span

Timeline

Image Region

Global

Severity Colors (Suggested)

Grouping Annotations