vtex-io-service-paths-and-cdn

Configure VTEX IO service.json route prefixes and Cache-Control headers.

Updated Mar 27, 2026
One-click install
npx skills add https://github.com/exilonX/ap2 --skill vtex-io-service-paths-and-cdn-exilonx
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vtex-io-service-paths-and-cdn
Source: https://github.com/exilonX/ap2/tree/main/.agents/skills/vtex-io-service-paths-and-cdn
Command: npx skills add https://github.com/exilonX/ap2 --skill vtex-io-service-paths-and-cdn-exilonx

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Prevents misconfigured VTEX IO service.json routes from breaking authentication context or causing edge/CDN caching to leak or serve the wrong data to the wrong shopper.

Core Features & Use Cases

  • Route path selection for cookie visibility: Decide when to use public (/yourPath), segment (/_v/segment/...), or private (/_v/private/...) prefixes to control whether vtex_segment and vtex_session are available to your service.
  • CDN-safe cache policy alignment: Configure Cache-Control (and related headers) so cacheability matches data sensitivity (anonymous vs segment vs authenticated).
  • Troubleshooting edge behavior: Debug missing cookies and unexpected CloudFront/edge results by aligning path prefix behavior with caching headers.

Quick Start

Ask the AI to recommend the correct service.json route path prefix and response Cache-Control headers for an endpoint that returns shopper-specific order history.

Frequently Asked Questions about vtex-io-service-paths-and-cdn

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I stop CloudFront from caching personalized VTEX IO responses?

To stop CloudFront from caching personalized VTEX IO responses, align your Cache-Control headers with data sensitivity and use private path prefixes like `/_v/private/...` for authenticated shopper data.

What is the correct service.json route path prefix for segment-scoped data in VTEX IO?

The correct service.json route path prefix for segment-scoped data in VTEX IO is `/_v/segment/...`, which ensures the `vtex_segment` and `vtex_session` cookies are available to your service.

Why are vtex_segment cookies missing from my VTEX IO service requests?

The vtex_segment cookies are missing because your service.json route uses a public path prefix instead of a segment or private prefix, preventing the edge from forwarding the required cookies.

How do I configure Cache-Control headers for anonymous versus authenticated VTEX IO endpoints?

Configure Cache-Control headers for VTEX IO endpoints by setting cacheable policies for anonymous public paths and restricting cacheability via private prefixes for authenticated endpoints to prevent edge leaks.

Can I use a public path prefix for VTEX IO routes that return shopper order history?

You cannot use a public path prefix for VTEX IO routes returning shopper order history because public paths restrict cookie visibility, preventing the service from accessing the required authentication context.

What's the best way to troubleshoot unexpected edge caching behavior in VTEX IO?

The best way to troubleshoot unexpected edge caching behavior in VTEX IO is to verify that your service.json path prefix matches the required cookie visibility and that Cache-Control aligns with data sensitivity.