Posts

List posts

Returns a list of posts.

GEThttps://api.cevoid.com/v2/posts

Request

curl 'https://api.cevoid.com/v2/posts' \
  -H "Authorization: Bearer ${CEVOID_API_KEY}"

fetch("https://api.cevoid.com/v2/posts", {
  headers: {
    Authorization: `Bearer ${process.env.CEVOID_API_KEY}`,
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data))

const response = await fetch("https://api.cevoid.com/v2/posts", {
  headers: {
    Authorization: `Bearer ${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/v2/posts",
    headers={
        "Authorization": f"Bearer {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/v2/posts',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . 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/v2/posts", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer " + 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/v2/posts")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{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

{
  "data": [
    {
      "id": "pst_summerlook",
      "profile_id": "prf_sarah",
      "added_by_workspace": false,
      "origin": {
        "type": "INSTAGRAM_TAGGED"
      },
      "type": "VIDEO",
      "status": "APPROVED",
      "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",
        "filename": "summer-look.jpg",
        "aspect_ratio": 1.25,
        "duration_seconds": 12.5,
        "has_audio": true
      },
      "caption": "Summer outfit",
      "hide_caption": false,
      "language": "en",
      "alt": "Person wearing a linen shirt",
      "video_captions": "WEBVTT\n\n00:00.000 --> 00:02.000\nSummer outfit.",
      "video_description": "A person shows a summer outfit.",
      "source": {
        "platform": "INSTAGRAM",
        "external_id": "18000000000000000",
        "url": "https://www.instagram.com/p/example/",
        "posted_at": "2026-08-01T09:00:00.000Z"
      },
      "custom_link": {
        "url": "https://shop.example.com/summer",
        "title": "Shop the summer edit",
        "description": "Explore the complete look.",
        "image_url": "https://cdn.cevoid.com/links/summer.jpg"
      },
      "labels": [
        "lbl_summer",
        "lbl_featured"
      ],
      "tagged_products": [
        {
          "product_id": "prd_abc123def456gh",
          "x": 0.35,
          "y": 0.65
        }
      ],
      "posted_at": "2026-08-01T09:00:00.000Z",
      "created_at": "2026-08-01T10:00:00.000Z",
      "updated_at": "2026-08-02T10:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6InBzdF9zdW1tZXJsb29rIn0"
}

Show all 58 linesShow fewer lines

{
  "additional_data": {
    "errors": [
      {
        "field": "query.market",
        "message": "Invalid input: expected string, received array"
      }
    ]
  },
  "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": {
    "errors": [
      {
        "field": "query.market",
        "message": "Invalid input: expected string, received array"
      }
    ]
  },
  "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"
}

Authorizations

Authorizationbearer tokenheaderrequired

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

Query parameters

cursorstring

Opaque cursor returned from a previous list response

Example: eyJpZCI6InBvc3RfMDEifQ

limitinteger

Page size between 1 and 100

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

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

marketstring

Market for included product presentations. Required when including products.

Length: 1 to 256
Example: mar_sweden

includestring | string[]

Comma-separated related data. Products requires an explicit market and products:read. Profiles requires profiles:read and returns canonical profiles referenced by profile_id.

Example: products,profiles

statusenum<string> | enum<string>[]Default: ["APPROVED","PENDING","DECLINED","NONE"]

Moderation states to include. The REMOVED moderation state is excluded unless requested explicitly. Processing, archived, and removed documents are never returned.

Example: ["APPROVED","PENDING"]

Response

200 Successful response application/json

dataobject[]required

Items returned for this page.

Item properties (21)

idstringrequired

Cevoid post ID.

Example: pst_abc123

profile_idstring

Cevoid profile ID for the contributor, when known.

Example: prf_abc123

added_by_workspacebooleanrequired

Whether the post was added by the workspace rather than a profile.

Example: false

custom_usernamestring

Post-specific display-name override, when set.

Example: The weekend crew

typeenum<string>required

Primary media type.

Allowed values: IMAGE VIDEO
Example: IMAGE

statusenum<string>required

Moderation state.

Allowed values: APPROVED PENDING DECLINED REMOVED NONE
Example: APPROVED

mediaobjectrequired

Properties (8)

urlstring<uri>required

Delivery URL for the media asset.

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

thumbnail_urlstring<uri>

Smaller preview image when available.

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

sprite_urlstring<uri>

Video sprite image for timeline previews when available.

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

blurhashstring

BlurHash placeholder for the media asset.

Example: LEHV6nWB2yk8pyo0adR*.7kCMdnj

filenamestring

Original filename, when available.

Example: summer-look.jpg

aspect_rationumber

Width divided by height.

Range: 0 < x
Example: 1.25

duration_secondsnumber

Video duration in seconds.

Range: 0 <= x
Example: 12.5

has_audioboolean

Whether video media includes an audio track.

Example: true

captionstring

Contributor caption.

Example: Summer outfit

hide_captionbooleanrequired

Whether clients should hide the caption.

Example: false

languagestring

IETF BCP 47 language tag for the caption.

Example: en

altstring

Alternative text for the media.

Example: Person wearing a linen shirt

video_captionsstring

WebVTT captions for video media.

Example: WEBVTT 00:00.000 --> 00:02.000 Summer outfit.

video_descriptionstring

Accessible description of video content.

Example: A person shows a summer outfit.

sourceobject

Properties (6)

platformenum<string>required

External platform where the post originated.

Allowed values: INSTAGRAM TIKTOK
Example: INSTAGRAM

carousel_indexinteger

Zero-based position within the source carousel. Omitted for standalone posts or unknown positions. Group slides by platform and external_id when available.

Range: 0 <= x
Example: 0

usernamestring

Source account username when stored with the post.

Example: sarah.lifestyle

external_idstring

Post identifier from the external platform.

Example: 18000000000000000

urlstring<uri>

Original public post URL.

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

posted_atstring<date-time>

ISO 8601 timestamp when the external post was published.

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

originobject

Properties (1)

typeenum<string>required

How the post entered the workspace. Omitted when the origin is unknown.

Allowed values: INSTAGRAM_FEED INSTAGRAM_HASHTAG INSTAGRAM_TAGGED INSTAGRAM_MENTIONED TIKTOK_FEED CEVOID_GENERAL CEVOID_CUSTOM WORKSPACE_UPLOADS WORKSPACE_COPIES WORKSPACE_IMPORTS ACTIVITIES
Example: WORKSPACE_UPLOADS

custom_linkobject

Properties (4)

urlstring<uri>required

Destination URL.

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

titlestringrequired

Link title.

Example: Shop the summer edit

descriptionstring

Link description.

Example: Explore the complete look.

image_urlstring<uri>

Link preview image.

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

labelsstring[]required

Cevoid label IDs assigned to the post.

Example: ["lbl_summer","lbl_featured"]

tagged_productsobject[]required

Item properties (3)

product_idstringrequired

Cevoid product ID.

Example: prd_abc123

xnumber

Normalized horizontal position.

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

ynumber

Normalized vertical position.

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

posted_atstring<date-time>required

Effective content date. Uses the stored posted date, falling back to the Instagram date, TikTok date, then creation date for legacy posts. Does not change list ordering.

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

created_atstring<date-time>required

ISO 8601 timestamp when the Post was created.

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

updated_atstring<date-time>required

ISO 8601 timestamp when the Post was last updated.

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

has_morebooleanrequired

Whether another page of results is available.

Example: true

next_cursorstring | nullrequired

Opaque cursor to request the next page, or null when the list is exhausted.

Example: eyJpZCI6InJlc291cmNlXzI1In0

includedobject

Properties (2)

productsobject[]

Products referenced by this page, localized to market. Join tagged_products.product_id to id.

Option 1: object

market_idstringrequired

Cevoid market ID for this product presentation.

Example: mar_sweden

external_idstring

Product identifier from the connected commerce platform.

Example: shopify_product_123

titlestring

Market-specific product title.

Example: Merino crew neck

variant_titlestring

Market-specific variant option label.

Example: Navy / M

skustring

Market-specific stock keeping unit.

Example: MERINO-NAVY-M

urlstring<uri>

Storefront URL for the selected market presentation.

Example: https://shop.example/products/merino-crew

image_urlstring<uri>

Primary image for the selected market presentation.

Example: https://cdn.cevoid.com/products/merino-crew/0.jpg

availabilityenum<string>

Availability for the selected market presentation.

Allowed values: IN_STOCK OUT_OF_STOCK
Example: IN_STOCK

idstringrequired

Cevoid product or variant ID.

Example: prd_abc123def456gh

typeenum<string>required

Product family.

Allowed value: PRODUCT
Example: PRODUCT

priceobject

Market-specific Product price range.

Properties (3)

currencystringrequired

ISO 4217 currency code.

Example: SEK

min_amountnumberrequired

Lowest Variant price.

Range: 0 <= x
Example: 799

max_amountnumberrequired

Highest Variant price.

Range: 0 <= x
Example: 999

Option 2: object

market_idstringrequired

Cevoid market ID for this product presentation.

Example: mar_sweden

external_idstring

Product identifier from the connected commerce platform.

Example: shopify_product_123

titlestring

Market-specific product title.

Example: Merino crew neck

variant_titlestring

Market-specific variant option label.

Example: Navy / M

skustring

Market-specific stock keeping unit.

Example: MERINO-NAVY-M

urlstring<uri>

Storefront URL for the selected market presentation.

Example: https://shop.example/products/merino-crew

image_urlstring<uri>

Primary image for the selected market presentation.

Example: https://cdn.cevoid.com/products/merino-crew/0.jpg

availabilityenum<string>

Availability for the selected market presentation.

Allowed values: IN_STOCK OUT_OF_STOCK
Example: IN_STOCK

idstringrequired

Cevoid product or variant ID.

Example: prd_abc123def456gh

typeenum<string>required

Purchasable Product variant.

Allowed value: VARIANT
Example: VARIANT

parent_product_idstringrequired

Cevoid product ID. Present when type is VARIANT.

Example: prd_abc123def456gh

priceobject

Market-specific Variant price.

Properties (3)

currencystringrequired

ISO 4217 currency code.

Example: SEK

amountnumberrequired

Current Variant price.

Range: 0 <= x
Example: 899

sale_amountnumber

Sale price when active.

Range: 0 <= x
Example: 799

profilesobject[]

Profiles referenced by this page. Join profile_id to id. Contains secret-key profile fields; keep server-side.

Item properties (19)

idstringrequired

Cevoid profile ID.

Example: prf_abc123

external_idstring

Identifier this profile carries in the workspace source system, when known. Secret-key only.

Example: 7391056823401

namestring

Display name of the profile.

Example: Sarah Johnson

first_namestring

First name of the profile.

Example: Sarah

last_namestring

Last name of the profile.

Example: Johnson

emailstring

Email address for the profile. Secret-key only.

Example: sarah.johnson@example.com

avatar_urlstring

Profile image URL.

Example: https://cdn.cevoid.com/avatars/profile123/profile.jpg

countrystring

Country code associated with the profile.

Example: US

languagestring

Preferred language code associated with the profile.

Example: en

locationstring

Free-form location associated with the profile. Secret-key only.

Example: San Francisco, CA

birthdaystring<date>

Birthday in YYYY-MM-DD format. Secret-key only.

Example: 1992-04-18

name_display_formatenum<string>

Preferred format for displaying the profile name.

Allowed values: FULL FIRST_LAST_INITIAL FIRST ANONYMOUS
Example: FIRST_LAST_INITIAL

biostring

Profile biography text. Secret-key only.

Example: Lifestyle blogger and photography enthusiast

notesstring

Notes visible only to secret keys.

Example: VIP customer, prefers email communication

created_atstring<date-time>required

ISO 8601 timestamp when the profile was created.

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

updated_atstring<date-time>required

ISO 8601 timestamp when the profile was last updated.

Example: 2024-01-20T14:22:15.000Z

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

400 Bad request application/json

additional_dataobject

Optional machine-readable error details.

Properties (1)

{key}any

statusnumberrequired

HTTP status code for the error response.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable description of the error.

Example: Route 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

statusnumberrequired

HTTP status code for the error response.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable description of the error.

Example: Route 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

statusnumberrequired

HTTP status code for the error response.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable description of the error.

Example: Route 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

statusnumberrequired

HTTP status code for the error response.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable description of the error.

Example: Route 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

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

statusnumberrequired

HTTP status code for the error response.

Example: 404

codestringrequired

Stable machine-readable error code.

Example: not_found

messagestringrequired

Human-readable description of the error.

Example: Route 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