Storefront UGC

List posts

Returns approved posts that match the requested filters.

GEThttps://api.widget.cevoid.com/v1/posts

Request

curl 'https://api.widget.cevoid.com/v1/posts?market=mar_sweden' \
  -H "Authorization: Bearer ${CEVOID_PUBLISHABLE_KEY}"

fetch("https://api.widget.cevoid.com/v1/posts?market=mar_sweden", {
  headers: {
    Authorization: "Bearer YOUR_PUBLISHABLE_KEY",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data))

const response = await fetch("https://api.widget.cevoid.com/v1/posts?market=mar_sweden", {
  headers: {
    Authorization: `Bearer ${process.env.CEVOID_PUBLISHABLE_KEY}`,
  },
})
if (!response.ok) throw new Error(`Request failed: ${response.status}`)
const data = await response.json()
console.log(data)

import os

import requests

response = requests.get(
    "https://api.widget.cevoid.com/v1/posts",
    params={
        "market": "mar_sweden",
    },
    headers={
        "Authorization": f"Bearer {os.environ['CEVOID_PUBLISHABLE_KEY']}",
    },
)
response.raise_for_status()
print(response.json())

<?php

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.widget.cevoid.com/v1/posts?market=mar_sweden',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('CEVOID_PUBLISHABLE_KEY'),
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://api.widget.cevoid.com/v1/posts?market=mar_sweden", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer " + os.Getenv("CEVOID_PUBLISHABLE_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}

require "net/http"

uri = URI("https://api.widget.cevoid.com/v1/posts?market=mar_sweden")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("CEVOID_PUBLISHABLE_KEY")}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts response.body

Response

{
  "data": [
    {
      "id": "pst_summerlook",
      "type": "IMAGE",
      "media": {
        "url": "https://cdn.cevoid.com/posts/pst_summerlook.jpg",
        "thumbnail_url": "https://cdn.cevoid.com/posts/pst_summerlook-thumbnail.jpg",
        "sprite_url": "https://cdn.cevoid.com/posts/pst_summerlook-sprite.jpg",
        "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
        "aspect_ratio": 0.8,
        "duration_seconds": 12.5,
        "has_audio": false
      },
      "caption": "A summer favorite.",
      "hide_caption": false,
      "alt": "Person wearing a beige linen shirt outdoors.",
      "source_url": "https://www.instagram.com/p/example/",
      "author": {
        "name": "@jane",
        "avatar_url": "https://cdn.cevoid.com/profiles/prf_jane.jpg"
      },
      "tagged_products": [
        {
          "id": "prd_linen_shirt",
          "type": "PRODUCT",
          "title": "Linen Shirt",
          "url": "https://shop.example.com/products/linen-shirt",
          "image_url": "https://cdn.cevoid.com/products/linen-shirt.jpg",
          "price": {
            "min_amount": 59.95,
            "max_amount": 79.95,
            "currency": "SEK"
          },
          "x": 0.35,
          "y": 0.65
        }
      ],
      "published_at": "2026-08-01T10:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJwdWJsaXNoZWRBdCI6IjIwMjYtMDgtMDFUMTA6MDA6MDAuMDAwWiJ9"
}

Show all 44 linesShow fewer lines

{
  "additional_data": {
    "property1": null,
    "property2": null
  },
  "status": 400,
  "code": "bad_request",
  "message": "Bad request",
  "request_id": "req_abc123"
}

{
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "request_id": "req_abc123"
}

{
  "status": 403,
  "code": "forbidden",
  "message": "Forbidden",
  "request_id": "req_abc123"
}

{
  "additional_data": {
    "property1": null,
    "property2": null
  },
  "status": 404,
  "code": "not_found",
  "message": "Resource not found",
  "request_id": "req_abc123"
}

{
  "additional_data": {
    "property1": null,
    "property2": null
  },
  "status": 422,
  "code": "validation_error",
  "message": "Validation error",
  "request_id": "req_abc123"
}

{
  "status": 429,
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "request_id": "req_abc123",
  "additional_data": {
    "retry_after_seconds": 1
  }
}

{
  "status": 500,
  "code": "internal_server_error",
  "message": "Internal server error",
  "request_id": "req_abc123"
}

{
  "status": 503,
  "code": "service_unavailable",
  "message": "Service unavailable",
  "request_id": "req_abc123"
}

Authorizations

Authorizationbearer tokenheaderrequired

Send Authorization: Bearer <key>, where the key is your publishable key.

Query parameters

marketstringrequired

Market identifier used for localized product data.

Length: 1 to 256
Example: mar_sweden

profile_idstring

Return posts attributed to this profile.

Length: 1 to 256
Example: prf_jane

label_idstring[]

Return posts with these labels. Repeat the parameter to provide more than one label.

Items: 1 to 50
Each item: length: 1 to 256
Example: ["lbl_summer","lbl_featured"]

label_matchenum<string>

Match any requested label (default) or require all requested labels. Requires label_id. Unknown labels are ignored for any; all returns no posts if any label is unknown. If no labels resolve, no posts are returned.

Allowed values: any all
Example: any

gallery_idstring

Return posts selected by this published gallery, newest first. Applies gallery filters but not pinned layout order.

Length: 1 to 256
Example: gal_summer

product_refstring

A Cevoid product or variant ID, provider-native ID, SKU, or barcode. Resolves within this workspace and market and selects the product family, including variants and existing tags. Unknown, ambiguous, or more than 100 candidate matches return an empty page; use a Cevoid product ID to disambiguate. Families with more than 1,000 product records return 400 with product_too_broad.

Length: 1 to 256
Example: gid://shopify/Product/123

external_collection_idstring

Return posts containing products in this market-specific external collection.

Length: 1 to 256
Example: summer-sale

cursorstring

Opaque cursor returned by the previous page. Keep all other query parameters unchanged.

Length: 1 to 2048
Example: eyJjcmVhdGVkQXQiOiIyMDI2LTA4LTAxVDEwOjAwOjAwLjAwMFoifQ

limitintegerDefault: 20

Number of posts to return, from 1 to 50.

Range: 1 <= x <= 50
Example: 20

Response

200 Successful response application/json

dataobject[]required

Item properties (13)

idstringrequired

Stable public Post identifier.

Length: 1 to 256
Example: pst_summerlook

typeenum<string>required

Post media type.

Allowed values: IMAGE VIDEO
Example: IMAGE

mediaobjectrequired

Properties (7)

urlstring<uri>required

CDN URL for the post media.

Example: https://cdn.cevoid.com/posts/pst_summerlook.jpg

thumbnail_urlstring<uri>

Smaller preview image when available.

Example: https://cdn.cevoid.com/posts/pst_summerlook-thumbnail.jpg

sprite_urlstring<uri>

Video sprite image for timeline previews when available.

Example: https://cdn.cevoid.com/posts/pst_summerlook-sprite.jpg

blurhashstring

BlurHash placeholder for the media asset.

Example: LEHV6nWB2yk8pyo0adR*.7kCMdnj

aspect_rationumber

Media width divided by height.

Range: 0 < x
Example: 0.8

duration_secondsnumber

Video duration in seconds.

Range: 0 <= x
Example: 12.5

has_audioboolean

Whether video media includes an audio track.

Example: true

captionstring

Public post caption. Omitted when hide_caption is true.

Example: A summer favorite.

hide_captionbooleanrequired

Whether clients should hide the caption.

Example: false

altstring

Accessible media description.

Example: Person wearing a beige linen shirt outdoors.

video_captionsstring

WebVTT captions for video media.

Example: WEBVTT 00:00.000 --> 00:02.000 A summer favorite.

video_descriptionstring

Accessible description of video content.

Example: A person turns to show the front and back of a linen shirt.

source_urlstring<uri>

Original public social post URL when available.

Example: https://www.instagram.com/p/example/

authorobject

Properties (2)

namestringrequired

Public display name selected for the storefront.

Example: @jane

avatar_urlstring<uri>

Public profile image URL when available.

Example: https://cdn.cevoid.com/profiles/prf_jane.jpg

custom_linkobject

Editorial link attached to this post.

Properties (4)

urlstring<uri>required

Example: https://shop.example.com/stories/summer

titlestring

Example: Summer stories

descriptionstring

Example: Explore our summer stories.

image_urlstring<uri>

Example: https://cdn.cevoid.com/stories/summer.jpg

tagged_productsobject[]required

Shoppable products in the selected market. Products without a presentation in that market are omitted.

Item properties (10)

idstringrequired

Stable public Product identifier.

Length: 1 to 256
Example: prd_linen_shirt

titlestringrequired

Market-specific product title.

Example: Linen Shirt

typeenum<string>required

Allowed values: PRODUCT VARIANT
Example: PRODUCT

parent_product_idstring

Length: 1 to 256
Example: prd_linen_shirt

availabilityenum<string>

Allowed values: IN_STOCK OUT_OF_STOCK
Example: IN_STOCK

urlstring<uri>

Market-specific storefront URL.

Example: https://shop.example.com/products/linen-shirt

image_urlstring<uri>

Market-specific product image URL.

Example: https://cdn.cevoid.com/products/linen-shirt.jpg

priceobject

Product price range or exact variant price in the selected market. Omitted when the market hides prices.

Option 1: object

currencystringrequired

min_amountnumberrequired

Range: 0 <= x

max_amountnumberrequired

Range: 0 <= x

Option 2: object

currencystringrequired

amountnumberrequired

Range: 0 <= x

sale_amountnumber

Range: 0 <= x

xnumber

Normalized horizontal hotspot position. Omitted together with y when no valid position is stored.

Range: 0 <= x <= 1
Example: 0.35

ynumber

Normalized vertical hotspot position.

Range: 0 <= x <= 1
Example: 0.65

published_atstring<date-time>required

Creation time in Cevoid, used for newest-first ordering. This can differ from the original social publication date.

Example: 2026-08-01T10:00:00.000Z

has_morebooleanrequired

Whether another page is available.

Example: true

next_cursorstring | nullrequired

Opaque cursor for the next page, or null when this is the final page.

Example: eyJwdWJsaXNoZWRBdCI6IjIwMjYtMDgtMDFUMTA6MDA6MDAuMDAwWiJ9

Response headers (7)

Cevoid-Processing-Msstring

End-to-end request processing time in milliseconds

Cevoid-Request-Idstring

Request identifier for support and tracing

RateLimit-Limitstring

Current rate limit bucket size

RateLimit-Remainingstring

Remaining requests in the current rate limit window

RateLimit-Resetinteger

Seconds until the next request token is available

Cache-Controlstring

Browser freshness is 60 seconds. Shared caches are fresh for five minutes and may serve stale content while revalidating for another five minutes. TTL is the only invalidation guarantee; moderation or removal may take up to ten minutes because no active purge is performed.

Varystring

Workspace credential headers included in the shared-cache key.

400 Bad request application/json

additional_dataobject

Optional machine-readable error details.

Properties (1)

{key}any | null

statusintegerrequired

HTTP status code.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable error description.

Example: Resource not found

request_idstring

Request identifier for support and tracing.

Example: req_abc123

Response headers (5)

Cevoid-Processing-Msstring

End-to-end request processing time in milliseconds

Cevoid-Request-Idstring

Request identifier for support and tracing

RateLimit-Limitstring

Current rate limit bucket size

RateLimit-Remainingstring

Remaining requests in the current rate limit window

RateLimit-Resetinteger

Seconds until the next request token is available

401 Unauthorized application/json

additional_dataobject

Optional machine-readable error details.

Properties (1)

{key}any | null

statusintegerrequired

HTTP status code.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable error description.

Example: Resource not found

request_idstring

Request identifier for support and tracing.

Example: req_abc123

Response headers (5)

Cevoid-Processing-Msstring

End-to-end request processing time in milliseconds

Cevoid-Request-Idstring

Request identifier for support and tracing

RateLimit-Limitstring

Current rate limit bucket size

RateLimit-Remainingstring

Remaining requests in the current rate limit window

RateLimit-Resetinteger

Seconds until the next request token is available

403 Forbidden application/json

additional_dataobject

Optional machine-readable error details.

Properties (1)

{key}any | null

statusintegerrequired

HTTP status code.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable error description.

Example: Resource not found

request_idstring

Request identifier for support and tracing.

Example: req_abc123

Response headers (5)

Cevoid-Processing-Msstring

End-to-end request processing time in milliseconds

Cevoid-Request-Idstring

Request identifier for support and tracing

RateLimit-Limitstring

Current rate limit bucket size

RateLimit-Remainingstring

Remaining requests in the current rate limit window

RateLimit-Resetinteger

Seconds until the next request token is available

404 Not found application/json

additional_dataobject

Optional machine-readable error details.

Properties (1)

{key}any | null

statusintegerrequired

HTTP status code.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable error description.

Example: Resource not found

request_idstring

Request identifier for support and tracing.

Example: req_abc123

Response headers (5)

Cevoid-Processing-Msstring

End-to-end request processing time in milliseconds

Cevoid-Request-Idstring

Request identifier for support and tracing

RateLimit-Limitstring

Current rate limit bucket size

RateLimit-Remainingstring

Remaining requests in the current rate limit window

RateLimit-Resetinteger

Seconds until the next request token is available

422 Validation error application/json

additional_dataobject

Optional machine-readable error details.

Properties (1)

{key}any | null

statusintegerrequired

HTTP status code.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable error description.

Example: Resource not found

request_idstring

Request identifier for support and tracing.

Example: req_abc123

Response headers (5)

Cevoid-Processing-Msstring

End-to-end request processing time in milliseconds

Cevoid-Request-Idstring

Request identifier for support and tracing

RateLimit-Limitstring

Current rate limit bucket size

RateLimit-Remainingstring

Remaining requests in the current rate limit window

RateLimit-Resetinteger

Seconds until the next request token is available

429 Too many requests application/json

additional_dataobjectrequired

Machine-readable rate-limit details.

Properties (2)

retry_after_secondsintegerrequired

Range: 0 <= x

{key}any | null

statusintegerrequired

HTTP status code.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable error description.

Example: Resource not found

request_idstring

Request identifier for support and tracing.

Example: req_abc123

Response headers (6)

Cevoid-Processing-Msstring

End-to-end request processing time in milliseconds

Cevoid-Request-Idstring

Request identifier for support and tracing

RateLimit-Limitstring

Current rate limit bucket size

RateLimit-Remainingstring

Remaining requests in the current rate limit window

RateLimit-Resetinteger

Seconds until the next request token is available

Retry-Afterinteger

Seconds to wait before retrying the request

500 Internal server error application/json

additional_dataobject

Optional machine-readable error details.

Properties (1)

{key}any | null

statusintegerrequired

HTTP status code.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable error description.

Example: Resource not found

request_idstring

Request identifier for support and tracing.

Example: req_abc123

Response headers (5)

Cevoid-Processing-Msstring

End-to-end request processing time in milliseconds

Cevoid-Request-Idstring

Request identifier for support and tracing

RateLimit-Limitstring

Current rate limit bucket size

RateLimit-Remainingstring

Remaining requests in the current rate limit window

RateLimit-Resetinteger

Seconds until the next request token is available

503 Service unavailable application/json

additional_dataobject

Optional machine-readable error details.

Properties (1)

{key}any | null

statusintegerrequired

HTTP status code.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable error description.

Example: Resource not found

request_idstring

Request identifier for support and tracing.

Example: req_abc123

Response headers (5)

Cevoid-Processing-Msstring

End-to-end request processing time in milliseconds

Cevoid-Request-Idstring

Request identifier for support and tracing

RateLimit-Limitstring

Current rate limit bucket size

RateLimit-Remainingstring

Remaining requests in the current rate limit window

RateLimit-Resetinteger

Seconds until the next request token is available