Posts

Get posts tagged with a specific product

Retrieve all posts that have been tagged with a specific product

GEThttps://api.cevoid.com/v1/products/{id}/posts

Request

curl 'https://api.cevoid.com/v1/products/product123/posts' \
  -H "x-api-key: ${CEVOID_API_KEY}"

fetch("https://api.cevoid.com/v1/products/product123/posts", {
  headers: {
    "x-api-key": process.env.CEVOID_API_KEY,
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data))

const response = await fetch("https://api.cevoid.com/v1/products/product123/posts", {
  headers: {
    "x-api-key": process.env.CEVOID_API_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.cevoid.com/v1/products/product123/posts",
    headers={
        "x-api-key": os.environ["CEVOID_API_KEY"],
    },
)
response.raise_for_status()
print(response.json())

<?php

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.cevoid.com/v1/products/product123/posts',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('CEVOID_API_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.cevoid.com/v1/products/product123/posts", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", os.Getenv("CEVOID_API_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.cevoid.com/v1/products/product123/posts")
request = Net::HTTP::Get.new(uri)
request["x-api-key"] = ENV.fetch("CEVOID_API_KEY")

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

Response

{
  "count": 0,
  "next": "string",
  "nodes": [
    {
      "id": "post_abc123def456",
      "origin": {
        "type": "instagram"
      },
      "alt": "Woman wearing sunglasses standing next to a red convertible car on a sunny beach",
      "videoCaptions": "Welcome to our summer collection! Check out these amazing sunglasses perfect for beach days.",
      "videoDescription": "Video shows a woman modeling sunglasses while walking along a sandy beach with palm trees in the background",
      "instagramUrl": "https://www.instagram.com/p/ABC123DEF456/",
      "type": "IMAGE",
      "fromInstagram": true,
      "addedByCompany": false,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "instagramDate": "2024-01-10T14:22:00.000Z",
      "media": {
        "location": "https://cdn.cevoid.com/media/posts/abc123.jpg",
        "hash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
        "filename": "summer-vacation-photo.jpg"
      },
      "comment": "Perfect day at the beach! ☀️ #SummerVibes #BeachLife #Sunglasses",
      "taggedProducts": [
        {
          "x": 0.35,
          "y": 0.65,
          "product": {
            "id": "prod_abc123",
            "title": "Wireless Bluetooth Headphones",
            "price": {
              "price": 99.99,
              "currency": "USD",
              "salePrice": 79.99
            },
            "category": "Electronics > Audio > Headphones",
            "media": {
              "location": "https://cdn.cevoid.com/media/products/headphones-main.jpg",
              "hash": "a1b2c3d4e5f6g7h8i9j0",
              "filename": "wireless-headphones-product-image.jpg"
            },
            "handle": "wireless-bluetooth-headphones",
            "url": "https://mystore.com/products/wireless-bluetooth-headphones",
            "developmentUrl": "https://dev.mystore.com/products/wireless-bluetooth-headphones",
            "sku": "WH-1000XM5-BLK",
            "mpn": "693903",
            "gtin": "7391998206837"
          }
        }
      ],
      "hideCaption": false,
      "uploadedBy": {
        "username": "john_doe_photography",
        "email": "sarah@example.com",
        "image": {
          "hash": "sha256:b2c3d4e5f6a7...",
          "filename": "profile-pic.jpg",
          "location": "https://cdn.cevoid.com/profiles/user123/avatar.jpg"
        }
      }
    }
  ]
}

Show all 64 linesShow fewer lines

"string"

"No valid API key provided"

"Something went wrong"

Authorizations

x-api-keystringheaderrequired

Send your API key in the x-api-key header.

Path parameters

idstringrequired

Product identifier, interpreted according to the id_type query parameter: the product's external ID (default), or a manufacturer part number when id_type=mpn

Example: product123

Query parameters

limitnumberDefault: 25

Max value for limit is 25

Range: 1 <= x <= 25
Example: 10

skipnumber | nullDefault: 0

Number of items to skip

Range: 0 <= x
Example: 0

marketstring

Market ID or shortId for localized content

Example: us

filterstring

JSON string array of filter criteria. See Core Concepts → Filtering for detailed filter structure and supported operators.

Example: [{"type":"label","operator":"OR","values":["507f1f77bcf86cd799439011","507f191e810c19729de860ea"]}]

id_typeenum<string>

How the {id} path parameter resolves to products. 'external_id' (default) matches the single product with that id from your platform. 'mpn' matches every product carrying that manufacturer part number and returns posts tagged with any of them, including color- and product-level tags on grouped products. An mpn matching more than 500 products returns 400.

Allowed values: external_id mpn
Example: mpn

Response

200 Successful response application/json

countnumberrequired

Total number of items

nextstring | nullrequired

URL for next page

nodesobject[]required

Item properties (16)

idstringrequired

Unique identifier for the post within the Cevoid system

Example: post_abc123def456

originobject

Properties (1)

typestringrequired

Source platform where the post originated (e.g., "instagram", "tiktok", "upload", "manual")

Example: instagram

altstring

Alternative text description for screen readers and accessibility tools, providing a text-based description of the visual content

Example: Woman wearing sunglasses standing next to a red convertible car on a sunny beach

videoCaptionsstring

Transcript or captions for video content, providing text representation of spoken words and audio cues

Example: Welcome to our summer collection! Check out these amazing sunglasses perfect for beach days.

videoDescriptionstring

Detailed description of video content including visual elements, actions, and scenes for accessibility

Example: Video shows a woman modeling sunglasses while walking along a sandy beach with palm trees in the background

instagramUrlstring

Original Instagram post URL if this content was imported from Instagram

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

typestring

Media type of the post content, typically "IMAGE" for photos or "VIDEO" for video content

Example: IMAGE

fromInstagramboolean

Indicates whether this post was imported from Instagram through social media integration

Example: true

addedByCompanyboolean

Indicates whether this post was uploaded directly by the company/brand rather than user-generated content

Example: false

createdAtstringrequired

ISO 8601 timestamp indicating when the post was first created or imported into the Cevoid system

Example: 2024-01-15T10:30:00.000Z

instagramDatestring

ISO 8601 timestamp of when the post was originally published on Instagram. Only present for Instagram-sourced content.

Example: 2024-01-10T14:22:00.000Z

mediaobjectrequired

Properties (3)

locationstringrequired

URL or CDN path to the media file (image or video)

Example: https://cdn.cevoid.com/media/posts/abc123.jpg

hashstring

Blurhash string for generating blur placeholder images while the media is loading. Use with the blurhash library to decode.

Example: LEHV6nWB2yk8pyo0adR*.7kCMdnj

filenamestring

Original filename when the media was uploaded, preserving the user's original file naming

Example: summer-vacation-photo.jpg

commentstring

Caption or comment text associated with the post, often containing hashtags, mentions, and descriptions

Example: Perfect day at the beach! ☀️ #SummerVibes #BeachLife #Sunglasses

taggedProductsobject[]required

Array of products that have been tagged or featured in this post, including their position coordinates and product details

Item properties (3)

xnumberrequired

Horizontal position coordinate (0-1) where the product is tagged on the image/video

Example: 0.35

ynumberrequired

Vertical position coordinate (0-1) where the product is tagged on the image/video

Example: 0.65

productobjectrequired

Complete product information including pricing, media, and links

Properties (11)

idstringrequired

Unique identifier for the product in the Cevoid system

Example: prod_abc123

titlestringrequired

Display name/title of the product as shown to customers

Example: Wireless Bluetooth Headphones

priceobject

Pricing information for the product including regular price, currency, and sale pricing

Properties (3)

pricenumber

Regular price of the product in the specified currency

Example: 99.99

currencystring

ISO 4217 currency code for the product pricing

Example: USD

salePricenumber

Discounted sale price if the product is currently on sale

Example: 79.99

categorystring

Product category or classification for organizational purposes

Example: Electronics > Audio > Headphones

mediaobject

Properties (3)

locationstringrequired

URL or CDN path to the media file (image or video)

Example: https://cdn.cevoid.com/media/posts/abc123.jpg

hashstring

Blurhash string for generating blur placeholder images while the media is loading. Use with the blurhash library to decode.

Example: LEHV6nWB2yk8pyo0adR*.7kCMdnj

filenamestring

Original filename when the media was uploaded, preserving the user's original file naming

Example: summer-vacation-photo.jpg

handlestringrequired

URL-friendly identifier for the product, typically used in product page URLs

Example: wireless-bluetooth-headphones

urlstring

Full URL to the product page on the e-commerce store

Example: https://mystore.com/products/wireless-bluetooth-headphones

developmentUrlstring

Development/staging URL for the product page, used for testing purposes

Example: https://dev.mystore.com/products/wireless-bluetooth-headphones

skustring

Stock keeping unit for the resolved product/variant. Omitted when the source feed does not provide one (e.g. Google Shopping feeds rarely map SKU).

Example: WH-1000XM5-BLK

mpnstring

Manufacturer part number. For grouped products this is typically the style-level number and is stable across sizes. Omitted when absent.

Example: 693903

gtinstring

Global Trade Item Number (UPC/EAN/ISBN) for the resolved variant. For a group-level (family) tag this may reflect a single representative variant rather than every size. Falls back to the barcode field for Shopify sources. Omitted when absent.

Example: 7391998206837

hideCaptionboolean

Setting to control whether the post caption should be hidden when displaying the post in galleries or widgets

Example: false

uploadedByobject

Properties (3)

usernamestringrequired

Username or display name of the user who uploaded/created this post

Example: john_doe_photography

emailstring

Email address of the member who submitted this post. Only included for inbox posts.

Example: sarah@example.com

imageobject

Profile image information for the user who uploaded this post

Properties (3)

hashstringrequired

Unique content hash for the user's profile image

Example: sha256:b2c3d4e5f6a7...

filenamestringrequired

Original filename of the user's profile image

Example: profile-pic.jpg

locationstringrequired

URL or CDN path to the user's profile image

Example: https://cdn.cevoid.com/profiles/user123/avatar.jpg

400 Bad request application/json

string

401 Unauthorized application/json

enum<string>

No valid API key provided

500 Internal server error application/json

enum<string>

Something went wrong