Content Artifacts

Artifacts in AdCP represent the content context adjacent to ad placements, enabling brand suitability evaluation without exposing raw content.

Artifacts

An artifact is a unit of content adjacent to an ad placement. When evaluating brand suitability, you’re asking: “Is this artifact appropriate for my brand’s ads?”

What Is an Artifact?

Artifacts represent the content context where an ad appears:

• A news article on a website
• A podcast segment between ad breaks
• A video chapter in a YouTube video
• A social media post in a feed
• A scene in a CTV show
• An AI-generated image in a chat conversation

Artifacts are identified by property_id + artifact_id - the property defines where the content lives, and the artifact_id is an opaque identifier for that specific piece of content. The artifact_id scheme is flexible - it could be a URL path, a platform-specific ID, or any consistent identifier the property owner uses internally.

Structure

Schema: artifact.json

Web article:

{
  "property_id": {"type": "domain", "value": "reddit.com"},
  "artifact_id": "r_fitness_post_abc123",
  "assets": [
    {"type": "text", "role": "title", "content": "Best protein sources for muscle building", "language": "en"},
    {"type": "text", "role": "paragraph", "content": "Looking for recommendations on high-quality protein sources...", "language": "en"},
    {"type": "image", "url": "https://cdn.reddit.com/fitness-image.jpg", "alt_text": "Person lifting weights"}
  ]
}

Podcast segment (note: no url — the property is identified by apple_podcast_id, and the audio asset uses a secured URL):

{
  "property_id": {"type": "apple_podcast_id", "value": "1234567890"},
  "artifact_id": "episode_42_segment_3",
  "assets": [
    {"type": "text", "role": "title", "content": "The Future of Running Shoes", "language": "en"},
    {"type": "audio", "url": "https://cdn.example.com/secured/ep42_seg3.mp3", "transcript": "Today we're talking to Dr. Chen about biomechanics research...", "duration_ms": 480000}
  ],
  "metadata": {
    "json_ld": [{"@type": "PodcastEpisode", "episodeNumber": 42}]
  }
}

CTV scene (the artifact_id encodes show, season, episode, and scene):

{
  "property_id": {"type": "app_id", "value": "com.streamingservice.tv"},
  "artifact_id": "show_running_s2e5_scene_14",
  "assets": [
    {"type": "text", "role": "title", "content": "Championship Race - Final Stretch", "language": "en"},
    {"type": "video", "url": "https://cdn.streaming.example.com/secured/s2e5_scene14.mp4", "transcript": "The runners round the final corner as the crowd erupts...", "duration_ms": 120000}
  ]
}

Required Fields

Field	Description
property_id	Where this artifact lives - uses standard identifier types (domain, app_id, apple_podcast_id, etc.)
artifact_id	Unique identifier within the property - the property owner defines their scheme
assets	Content in document order - text blocks, images, video, audio

Optional Fields

Field	Description
variant_id	Identifies a specific variant (A/B test, translation, temporal version)
format_id	Reference to format registry (same as creative formats)
url	Web URL if the artifact has one
metadata	Artifact-level metadata (Open Graph, JSON-LD, author info)
published_time	When the artifact was published
last_update_time	When the artifact was last modified

Variants

The same artifact may have multiple variants:

• Translations - English version vs Spanish version
• A/B tests - Different headlines being tested
• Temporal versions - Content that changed on Wednesday

Use variant_id to distinguish between them:

// English version
{
  "property_id": {"type": "domain", "value": "nytimes.com"},
  "artifact_id": "article_12345",
  "variant_id": "en",
  "assets": [
    {"type": "text", "role": "title", "content": "Breaking News Story", "language": "en"}
  ]
}

// Spanish translation
{
  "property_id": {"type": "domain", "value": "nytimes.com"},
  "artifact_id": "article_12345",
  "variant_id": "es",
  "assets": [
    {"type": "text", "role": "title", "content": "Noticia de última hora", "language": "es"}
  ]
}

// A/B test variant
{
  "property_id": {"type": "domain", "value": "nytimes.com"},
  "artifact_id": "article_12345",
  "variant_id": "headline_test_b",
  "assets": [
    {"type": "text", "role": "title", "content": "Alternative Headline Being Tested", "language": "en"}
  ]
}

The combination of artifact_id + variant_id must be unique within a property. This lets you track which variant a user saw and correlate it with delivery reports.

Asset Types

Assets are the actual content within an artifact. Everything is an asset - titles, paragraphs, images, videos.

Text

{"type": "text", "role": "title", "content": "Article Title", "language": "en"}
{"type": "text", "role": "paragraph", "content": "The article body text...", "language": "en"}
{"type": "text", "role": "description", "content": "A summary of the article", "language": "en"}
{"type": "text", "role": "heading", "content": "Section Header", "heading_level": 2}
{"type": "text", "role": "quote", "content": "A quoted statement"}

Roles: title, description, paragraph, heading, caption, quote, list_item

Each text asset can have its own language tag for mixed-language content.

Image

{
  "type": "image",
  "url": "https://cdn.example.com/photo.jpg",
  "alt_text": "Description of the image"
}

Video

{
  "type": "video",
  "url": "https://cdn.example.com/video.mp4",
  "transcript": "Full transcript of the video content...",
  "duration_ms": 180000
}

Audio

{
  "type": "audio",
  "url": "https://cdn.example.com/podcast.mp3",
  "transcript": "Today we're discussing...",
  "duration_ms": 3600000
}

Metadata

Artifact-level metadata describes the artifact as a whole, not individual assets:

{
  "metadata": {
    "author": "Jane Smith",
    "canonical": "https://example.com/article/12345",
    "open_graph": {
      "og:type": "article",
      "og:site_name": "Example News"
    },
    "json_ld": [
      {
        "@type": "NewsArticle",
        "datePublished": "2025-01-15"
      }
    ]
  }
}

This is separate from assets because it’s about the artifact container, not the content itself.

Secured Asset Access

Many assets aren’t publicly accessible - AI-generated images, private conversations, paywalled content. The artifact schema supports authenticated access.

Pre-Configuration (Recommended)

For ongoing partnerships, configure access once during onboarding rather than per-request:

1. Service account sharing - Grant the verification agent access to your cloud storage
2. OAuth client credentials - Set up machine-to-machine authentication
3. API key exchange - Share long-lived API keys during setup

This happens during the activation phase when the seller first receives content standards from a buyer.

Per-Asset Authentication

When pre-configured identity access isn’t possible, attach a short-lived, asset-scoped token to individual assets:

{
  "type": "image",
  "url": "https://cdn.openai.com/secured/img_abc123.png",
  "access": {
    "method": "bearer_token",
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Note on token size: For artifacts with many assets, per-asset tokens can significantly increase payload size. Consider:

1. Pre-configured access - Set up service account access once during onboarding
2. Shared token reference - Define tokens at the artifact level and reference by ID
3. Signed URLs - Use pre-signed URLs where the URL itself is the credential

The url field is the access URL - it may differ from the artifact’s canonical/published URL. For example, a published article at https://news.example.com/article/123 might have assets served from https://cdn.example.com/secured/....

Access Methods

Method	Use Case
bearer_token	Short-lived, asset-scoped OAuth2 token in the Authorization header. The only method that carries a live secret in the payload — treat it as a secret (never log it or place it in model context).
service_account	Identity-based access. The seller pre-authorizes the caller’s own service account; no credentials are transmitted.
signed_url	Pre-signed URL — the URL itself is the (time-limited) credential.

Service Account Access

service_account is identity-based — no credentials are sent in the response. During onboarding the seller grants the buyer’s (or verification agent’s) own service account read access to the asset store; at fetch time the client authenticates with that identity using the cloud provider’s normal credential chain (GCP Application Default Credentials, AWS SigV4).

For GCP:

{
  "access": {
    "method": "service_account",
    "provider": "gcp"
  }
}

For AWS:

{
  "access": {
    "method": "service_account",
    "provider": "aws"
  }
}

Never place service-account keys, private keys, or access secrets in a response payload — they would travel across agent transport, logs, and model context. Identity-based access keeps secrets off the wire entirely.

Pre-Signed URLs

For one-off access without sharing credentials:

{
  "type": "video",
  "url": "https://storage.googleapis.com/bucket/video.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=...&X-Goog-Signature=...",
  "access": {
    "method": "signed_url"
  }
}

The URL itself contains the credentials - no additional authentication needed.

Property Identifier Types

The property_id uses standard identifier types from the AdCP property schema:

Type	Example	Use Case
domain	reddit.com	Websites
app_id	com.spotify.music	Mobile apps
apple_podcast_id	1234567890	Apple Podcasts
spotify_collection_id	4rOoJ6Egrf8K2IrywzwOMk	Spotify podcasts
youtube_channel_id	UCddiUEpeqJcYeBxX1IVBKvQ	YouTube channels
rss_url	https://feeds.example.com/podcast.xml	RSS feeds

Artifact ID Schemes

The property owner defines their artifact_id scheme. Examples:

Property Type	Artifact ID Pattern	Example
News website	article_{id}	article_12345
Reddit	r_{subreddit}_{post_id}	r_fitness_abc123
Podcast	episode_{num}_segment_{num}	episode_42_segment_2
CTV	show_{id}_s{season}e{episode}_scene_{num}	show_abc_s3e5_scene_12
Social feed	post_{id}	post_xyz789

The verification agent doesn’t need to understand the scheme - it’s opaque. The property owner uses it to correlate artifacts with their content.

Related

• Content Standards Overview - How artifacts fit into the content standards workflow
• calibrate_content - Sending artifacts for calibration