API Technical Specifications

📘
Parameters marked with an asterisk (*) are mandatory.

Endpoint

Environment	URL
Production	`https://edge.curalate.com/v1/structured-data/content`

HTTP Method

GET

Parameters

Parameter	Placement	Description	Example
`q`*	Query	JSON object with `galleries` array specifying which galleries to fetch. See Request query parameters (q) for schema details.	`{"galleries":[{"dataSourceId":"abc123"}]}`
`locale`	Query	Locale for product names and metadata. Format: `languageCode_countryCode`.	`en_US`
`canonical`	Query	Page canonical URL with fragment identifier. When provided with `productId`, enables `@id` injection for Schema.org entity merging.	`https://www.example.com/products/shoe#product`
`productId`	Query	Product identifier for `@id` injection. When both `canonical` and `productId` are provided, gallery items referencing this product get `@id` set to the canonical URL.	`35T5G845E6L`
`User-Agent`	Header	Your server's User-Agent identifier.	`Java-http-client/17.0.7`
`Accept`	Header	Response format. Default: `text/javascript`. Options: `text/javascript`, `application/ld+json`, `text/html`.	`text/javascript`
`Bv-Forwarded-User-Agent`	Header	Original AI crawler's User-Agent string. Enables crawler traffic analytics.	`Mozilla/5.0 (compatible; GPTBot/1.0)`

Request Query Parameters (q)

The q parameter accepts a JSON object with a galleries array. Each gallery object supports the following parameters:

Parameter	Description	Example
`dataSourceId`*	Gallery data source identifier, available in the dashboard	`aBcDeFgHiJkLmNoP`
`filter`	Gallery filter expression. Must match frontend widget filter for anti-cloaking compliance.	`productId:SKU123`
`sort`	Sort order. Options: `Latest`, `Likes`, `Optimized`. Default: `Optimized`.	`Latest`
`limit`	Maximum items to return. Default: 10. Maximum: 50.	`10`
`after`	Forward pagination cursor from previous response.	`cursor_abc123`
`before`	Reverse pagination cursor.	`cursor_xyz789`

For filter syntax details, see Media Filters.

SAMPLE REQUESTS AND RESPONSES

Retrieve Data in JSON-LD

JSON-LD is the default format for gallery structured data. To retrieve gallery content in JSON-LD format, include the galleries array in your request.

Retrieve Gallery in JSON-LD

Sample Request

curl --location 'https://edge.curalate.com/v1/structured-data/content?q={"galleries":[{"dataSourceId":"aBcDeFgHiJkLmNoP"}]}&locale=en_US' \
--header 'Accept: text/javascript' \
--header 'User-Agent: Java-http-client/17.0.7' \
--header 'Bv-Forwarded-User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot'

Sample Response

<script type="application/ld+json" id="bv-geo-jsonld-gallery-1-data">
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "Visual Gallery",
  "numberOfItems": 156,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "VideoObject",
        "name": "Morning skincare routine that changed everything",
        "description": "Morning skincare routine that changed everything. Finally found the perfect combination for my sensitive skin. The glow is unreal! #skincare #morningroutine #glowingskin",
        "uploadDate": "2026-05-18T09:30:00Z",
        "contentUrl": "https://edge.curalate.com/v1/vid/aBcDeFgHiJkLmNoPqRsTuVwXyZ=/h",
        "thumbnailUrl": "https://edge.curalate.com/v1/img/aBcDeFgHiJkLmNoPqRsTuVwXyZ=/sc/300x300",
        "creator": {
          "@type": "Person",
          "name": "Emma Thompson",
          "alternateName": "@emmathompson_beauty",
          "url": "https://instagram.com/emmathompson_beauty"
        },
        "creditText": "@emmathompson_beauty via Instagram",
        "copyrightNotice": "© Emma Thompson. Used with permission.",
        "isBasedOn": "https://www.instagram.com/reel/CxYz123AbCd/",
        "interactionStatistic": [
          {
            "@type": "InteractionCounter",
            "interactionType": "LikeAction",
            "userInteractionCount": 8542
          },
          {
            "@type": "InteractionCounter",
            "interactionType": "CommentAction",
            "userInteractionCount": 127
          }
        ]
      }
    },
    {
      "@type": "ListItem",
      "position": 2,
      "item": {
        "@type": "ImageObject",
        "name": "Date night look complete",
        "description": "Date night look complete. This lipstick shade is absolutely stunning - the perfect rose with a hint of berry. Lasted through dinner and dessert! #datenight #lipstick #makeuplook",
        "uploadDate": "2026-05-15T19:45:00Z",
        "contentUrl": "https://edge.curalate.com/v1/img/xYz789AbCdEfGhIjKlMnOp=",
        "thumbnailUrl": "https://edge.curalate.com/v1/img/xYz789AbCdEfGhIjKlMnOp=/sc/300x300",
        "creator": {
          "@type": "Person",
          "name": "Sophia Chen",
          "alternateName": "@sophiastyle",
          "url": "https://instagram.com/sophiastyle"
        },
        "creditText": "@sophiastyle via Instagram",
        "copyrightNotice": "© Sophia Chen. Used with permission.",
        "isBasedOn": "https://www.instagram.com/p/DeFgHiJ456/",
        "interactionStatistic": [
          {
            "@type": "InteractionCounter",
            "interactionType": "LikeAction",
            "userInteractionCount": 12350
          },
          {
            "@type": "InteractionCounter",
            "interactionType": "CommentAction",
            "userInteractionCount": 89
          }
        ]
      }
    }
  ]
}
</script>

Retrieve Gallery with Tagged Products

When gallery items have tagged products, they appear in the about array.

Sample Request

curl --location 'https://edge.curalate.com/v1/structured-data/content?q={"galleries":[{"dataSourceId":"aBcDeFgHiJkLmNoP","filter":"productId:PRD-12345"}]}&locale=en_US' \
--header 'Accept: text/javascript' \
--header 'User-Agent: Java-http-client/17.0.7' \
--header 'Bv-Forwarded-User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot'

Sample Response

<script type="application/ld+json" id="bv-geo-jsonld-gallery-1-data">
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "Visual Gallery",
  "numberOfItems": 24,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "ImageObject",
        "name": "Summer essential found",
        "description": "Summer essential found. This lightweight moisturizer is perfect for hot days - hydrating without feeling heavy. My skin has never looked better! #summerskincare #moisturizer #skincareroutine",
        "uploadDate": "2026-06-10T14:20:00Z",
        "contentUrl": "https://edge.curalate.com/v1/img/MnOpQrStUvWxYz123456=",
        "thumbnailUrl": "https://edge.curalate.com/v1/img/MnOpQrStUvWxYz123456=/sc/300x300",
        "creator": {
          "@type": "Person",
          "name": "Olivia Martinez",
          "alternateName": "@olivia_glows",
          "url": "https://instagram.com/olivia_glows"
        },
        "creditText": "@olivia_glows via Instagram",
        "copyrightNotice": "© Olivia Martinez. Used with permission.",
        "isBasedOn": "https://www.instagram.com/p/GhIjKlM789/",
        "interactionStatistic": [
          {
            "@type": "InteractionCounter",
            "interactionType": "LikeAction",
            "userInteractionCount": 6720
          },
          {
            "@type": "InteractionCounter",
            "interactionType": "CommentAction",
            "userInteractionCount": 156
          }
        ],
        "about": [
          {
            "@type": "Thing",
            "name": "Hydra Glow Lightweight Moisturizer SPF 30 | 1.7 fl oz",
            "url": "https://www.example.com/skincare/moisturizers/hydra-glow-spf30/PRD-12345.html"
          }
        ]
      }
    }
  ]
}
</script>

Supported Markup Schema

Attribute	Description
`@context`	Schema.org context URL
`@type`	`ItemList` for gallery container
`name`	Gallery name
`numberOfItems`	Total count of items in the gallery
`itemListElement`	Array of `ListItem` objects

ListItem

Attribute	Description
`@type`	`ListItem`
`position`	1-based position in the list
`item`	`ImageObject` or `VideoObject`

ImageObject / VideoObject

Attribute	Description
`@type`	`ImageObject` or `VideoObject`
`name`	Post caption (first line)
`description`	Full post caption
`uploadDate`	ISO 8601 timestamp
`contentUrl`	Full-resolution media URL
`thumbnailUrl`	Thumbnail URL
`creator`	`Person` object with creator info
`creditText`	Attribution text
`copyrightNotice`	Copyright notice
`isBasedOn`	Original social media post URL
`interactionStatistic`	Array of engagement metrics
`about`	Array of tagged products (when available)

Person (Creator)

Attribute	Description
`@type`	`Person`
`name`	Creator's display name
`alternateName`	Social media handle
`url`	Profile URL

InteractionCounter

Attribute	Description
`@type`	`InteractionCounter`
`interactionType`	`LikeAction` or `CommentAction`
`userInteractionCount`	Count of interactions

Thing (Product)

Attribute	Description
`@type`	`Thing`
`name`	Product name
`url`	Product page URL

Retrieve Data in Microdata

To retrieve gallery structured data in Microdata format, send text/html in the Accept request header.

Sample Request

curl --location 'https://edge.curalate.com/v1/structured-data/content?q={"galleries":[{"dataSourceId":"aBcDeFgHiJkLmNoP"}]}&locale=en_US' \
--header 'Accept: text/html' \
--header 'User-Agent: Java-http-client/17.0.7' \
--header 'Bv-Forwarded-User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot'

Sample Response

<div itemscope itemtype="https://schema.org/ItemList">
    <meta itemprop="name" content="Visual Gallery">
    <meta itemprop="numberOfItems" content="156">
    
    <div itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
        <meta itemprop="position" content="1">
        <div itemprop="item" itemscope itemtype="https://schema.org/VideoObject">
            <meta itemprop="name" content="Morning skincare routine that changed everything">
            <meta itemprop="description" content="Morning skincare routine that changed everything. Finally found the perfect combination for my sensitive skin. The glow is unreal! #skincare #morningroutine #glowingskin">
            <meta itemprop="uploadDate" content="2026-05-18T09:30:00Z">
            <meta itemprop="contentUrl" content="https://edge.curalate.com/v1/vid/aBcDeFgHiJkLmNoPqRsTuVwXyZ=/h">
            <meta itemprop="thumbnailUrl" content="https://edge.curalate.com/v1/img/aBcDeFgHiJkLmNoPqRsTuVwXyZ=/sc/300x300">
            <span itemprop="creator" itemscope itemtype="https://schema.org/Person">
                <meta itemprop="name" content="Emma Thompson">
                <meta itemprop="alternateName" content="@emmathompson_beauty">
                <meta itemprop="url" content="https://instagram.com/emmathompson_beauty">
            </span>
            <meta itemprop="creditText" content="@emmathompson_beauty via Instagram">
            <meta itemprop="copyrightNotice" content="© Emma Thompson. Used with permission.">
            <meta itemprop="isBasedOn" content="https://www.instagram.com/reel/CxYz123AbCd/">
            <span itemprop="interactionStatistic" itemscope itemtype="https://schema.org/InteractionCounter">
                <meta itemprop="interactionType" content="LikeAction">
                <meta itemprop="userInteractionCount" content="8542">
            </span>
            <span itemprop="interactionStatistic" itemscope itemtype="https://schema.org/InteractionCounter">
                <meta itemprop="interactionType" content="CommentAction">
                <meta itemprop="userInteractionCount" content="127">
            </span>
        </div>
    </div>
    
    <div itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
        <meta itemprop="position" content="2">
        <div itemprop="item" itemscope itemtype="https://schema.org/ImageObject">
            <meta itemprop="name" content="Date night look complete">
            <meta itemprop="description" content="Date night look complete. This lipstick shade is absolutely stunning - the perfect rose with a hint of berry. Lasted through dinner and dessert! #datenight #lipstick #makeuplook">
            <meta itemprop="uploadDate" content="2026-05-15T19:45:00Z">
            <meta itemprop="contentUrl" content="https://edge.curalate.com/v1/img/xYz789AbCdEfGhIjKlMnOp=">
            <meta itemprop="thumbnailUrl" content="https://edge.curalate.com/v1/img/xYz789AbCdEfGhIjKlMnOp=/sc/300x300">
            <span itemprop="creator" itemscope itemtype="https://schema.org/Person">
                <meta itemprop="name" content="Sophia Chen">
                <meta itemprop="alternateName" content="@sophiastyle">
                <meta itemprop="url" content="https://instagram.com/sophiastyle">
            </span>
            <meta itemprop="creditText" content="@sophiastyle via Instagram">
            <meta itemprop="copyrightNotice" content="© Sophia Chen. Used with permission.">
            <meta itemprop="isBasedOn" content="https://www.instagram.com/p/DeFgHiJ456/">
            <span itemprop="interactionStatistic" itemscope itemtype="https://schema.org/InteractionCounter">
                <meta itemprop="interactionType" content="LikeAction">
                <meta itemprop="userInteractionCount" content="12350">
            </span>
            <span itemprop="interactionStatistic" itemscope itemtype="https://schema.org/InteractionCounter">
                <meta itemprop="interactionType" content="CommentAction">
                <meta itemprop="userInteractionCount" content="89">
            </span>
        </div>
    </div>
</div>

Retrieve Data in JSON

To retrieve gallery structured data in JSON format, send application/ld+json in the Accept request header.

Sample Request

curl --location 'https://edge.curalate.com/v1/structured-data/content?q={"galleries":[{"dataSourceId":"aBcDeFgHiJkLmNoP"}]}&locale=en_US' \
--header 'Accept: application/ld+json' \
--header 'User-Agent: Java-http-client/17.0.7' \
--header 'Bv-Forwarded-User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot'

Sample Response

{
  "galleries": [
    {
      "@context": "https://schema.org",
      "@type": "ItemList",
      "name": "Visual Gallery",
      "numberOfItems": 156,
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "item": {
            "@type": "VideoObject",
            "name": "Morning skincare routine that changed everything",
            "description": "Morning skincare routine that changed everything. Finally found the perfect combination for my sensitive skin. The glow is unreal! #skincare #morningroutine #glowingskin",
            "uploadDate": "2026-05-18T09:30:00Z",
            "contentUrl": "https://edge.curalate.com/v1/vid/aBcDeFgHiJkLmNoPqRsTuVwXyZ=/h",
            "thumbnailUrl": "https://edge.curalate.com/v1/img/aBcDeFgHiJkLmNoPqRsTuVwXyZ=/sc/300x300",
            "creator": {
              "@type": "Person",
              "name": "Emma Thompson",
              "alternateName": "@emmathompson_beauty",
              "url": "https://instagram.com/emmathompson_beauty"
            },
            "creditText": "@emmathompson_beauty via Instagram",
            "copyrightNotice": "© Emma Thompson. Used with permission.",
            "isBasedOn": "https://www.instagram.com/reel/CxYz123AbCd/",
            "interactionStatistic": [
              {
                "@type": "InteractionCounter",
                "interactionType": "LikeAction",
                "userInteractionCount": 8542
              },
              {
                "@type": "InteractionCounter",
                "interactionType": "CommentAction",
                "userInteractionCount": 127
              }
            ]
          }
        },
        {
          "@type": "ListItem",
          "position": 2,
          "item": {
            "@type": "ImageObject",
            "name": "Date night look complete",
            "description": "Date night look complete. This lipstick shade is absolutely stunning - the perfect rose with a hint of berry. Lasted through dinner and dessert! #datenight #lipstick #makeuplook",
            "uploadDate": "2026-05-15T19:45:00Z",
            "contentUrl": "https://edge.curalate.com/v1/img/xYz789AbCdEfGhIjKlMnOp=",
            "thumbnailUrl": "https://edge.curalate.com/v1/img/xYz789AbCdEfGhIjKlMnOp=/sc/300x300",
            "creator": {
              "@type": "Person",
              "name": "Sophia Chen",
              "alternateName": "@sophiastyle",
              "url": "https://instagram.com/sophiastyle"
            },
            "creditText": "@sophiastyle via Instagram",
            "copyrightNotice": "© Sophia Chen. Used with permission.",
            "isBasedOn": "https://www.instagram.com/p/DeFgHiJ456/",
            "interactionStatistic": [
              {
                "@type": "InteractionCounter",
                "interactionType": "LikeAction",
                "userInteractionCount": 12350
              },
              {
                "@type": "InteractionCounter",
                "interactionType": "CommentAction",
                "userInteractionCount": 89
              }
            ]
          }
        }
      ]
    }
  ]
}

Send Filters, Limit, and Sort Options

You can pass filters, limit, and sort parameters in the q parameter to control which gallery content is returned.

For filter syntax details, see Media Filters.

Pagination

The API supports cursor-based pagination using the after and before parameters. To retrieve subsequent pages, pass the cursor value from the previous response.

⚠️
Crawler Visibility Limitation
Due to technical constraints, crawlers can only access the first page of gallery data. While the after parameter allows your application to fetch additional pages via the Media API, this paginated content is not visible to search engine or AI crawlers.

Sample Request

curl --location 'https://edge.curalate.com/v1/structured-data/content?q={"galleries":[{"dataSourceId":"aBcDeFgHiJkLmNoP","filter":"productId:PRD-12345","limit":5,"sort":"Latest"}]}&locale=en_US' \
--header 'Accept: text/javascript' \
--header 'User-Agent: Java-http-client/17.0.7' \
--header 'Bv-Forwarded-User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot'

Sample Response

<script type="application/ld+json" id="bv-geo-jsonld-gallery-1-data">
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "Visual Gallery",
  "numberOfItems": 5,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "ImageObject",
        "name": "Summer essential found",
        "description": "Summer essential found. This lightweight moisturizer is perfect for hot days - hydrating without feeling heavy. My skin has never looked better! #summerskincare #moisturizer #skincareroutine",
        "uploadDate": "2026-06-10T14:20:00Z",
        "contentUrl": "https://edge.curalate.com/v1/img/MnOpQrStUvWxYz123456=",
        "thumbnailUrl": "https://edge.curalate.com/v1/img/MnOpQrStUvWxYz123456=/sc/300x300",
        "creator": {
          "@type": "Person",
          "name": "Olivia Martinez",
          "alternateName": "@olivia_glows",
          "url": "https://instagram.com/olivia_glows"
        },
        "creditText": "@olivia_glows via Instagram",
        "copyrightNotice": "© Olivia Martinez. Used with permission.",
        "isBasedOn": "https://www.instagram.com/p/GhIjKlM789/",
        "interactionStatistic": [
          {
            "@type": "InteractionCounter",
            "interactionType": "LikeAction",
            "userInteractionCount": 6720
          },
          {
            "@type": "InteractionCounter",
            "interactionType": "CommentAction",
            "userInteractionCount": 156
          }
        ],
        "about": [
          {
            "@type": "Thing",
            "name": "Hydra Glow Lightweight Moisturizer SPF 30 | 1.7 fl oz",
            "url": "https://www.example.com/skincare/moisturizers/hydra-glow-spf30/PRD-12345.html"
          }
        ]
      }
    },
    {
      "@type": "ListItem",
      "position": 2,
      "item": {
        "@type": "VideoObject",
        "name": "Get ready with me using my holy grail",
        "description": "Get ready with me using my holy grail. This moisturizer has been my secret weapon all summer. Watch till the end for application tips! #grwm #skincaretips #holygrail",
        "uploadDate": "2026-06-08T11:15:00Z",
        "contentUrl": "https://edge.curalate.com/v1/vid/QrStUvWxYz789AbCd=",
        "thumbnailUrl": "https://edge.curalate.com/v1/img/QrStUvWxYz789AbCd=/sc/300x300",
        "creator": {
          "@type": "Person",
          "name": "Isabella Nguyen",
          "alternateName": "@bella_beauty",
          "url": "https://instagram.com/bella_beauty"
        },
        "creditText": "@bella_beauty via Instagram",
        "copyrightNotice": "© Isabella Nguyen. Used with permission.",
        "isBasedOn": "https://www.instagram.com/reel/KlMnOpQ012/",
        "interactionStatistic": [
          {
            "@type": "InteractionCounter",
            "interactionType": "LikeAction",
            "userInteractionCount": 9845
          },
          {
            "@type": "InteractionCounter",
            "interactionType": "CommentAction",
            "userInteractionCount": 234
          }
        ],
        "about": [
          {
            "@type": "Thing",
            "name": "Hydra Glow Lightweight Moisturizer SPF 30 | 1.7 fl oz",
            "url": "https://www.example.com/skincare/moisturizers/hydra-glow-spf30/PRD-12345.html"
          }
        ]
      }
    }
  ]
}
</script>