> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cevoid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List posts

> Returns approved posts that match the requested filters.



## OpenAPI

````yaml /openapi/widget-api.json get /v1/posts
openapi: 3.0.3
info:
  title: Cevoid Widget API
  version: 1.0.0
servers:
  - url: https://api.widget.cevoid.com
    description: Production
  - url: http://localhost:3007
    description: Development
security: []
paths:
  /v1/posts:
    get:
      tags:
        - Storefront UGC
      summary: List posts
      description: Returns approved posts that match the requested filters.
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 256
            description: Market identifier used for localized product data.
            example: mar_sweden
          required: true
          description: Market identifier used for localized product data.
          name: market
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 256
            description: Return posts attributed to this profile.
            example: prf_jane
          required: false
          description: Return posts attributed to this profile.
          name: profile_id
          in: query
        - schema:
            type: array
            items:
              type: string
              minLength: 1
              maxLength: 256
              description: Stable public label identifier.
              example: lbl_summer
            minItems: 1
            maxItems: 50
            description: >-
              Return posts with these labels. Repeat the parameter to provide
              more than one label.
            example:
              - lbl_summer
              - lbl_featured
          required: false
          description: >-
            Return posts with these labels. Repeat the parameter to provide more
            than one label.
          name: label_id
          in: query
        - schema:
            type: string
            enum:
              - any
              - all
            description: >-
              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.
            example: any
          required: false
          description: >-
            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.
          name: label_match
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 256
            description: >-
              Return posts selected by this published gallery, newest first.
              Applies gallery filters but not pinned layout order.
            example: gal_summer
          required: false
          description: >-
            Return posts selected by this published gallery, newest first.
            Applies gallery filters but not pinned layout order.
          name: gallery_id
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 256
            description: >-
              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.
            example: gid://shopify/Product/123
          required: false
          description: >-
            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.
          name: product_ref
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 256
            description: >-
              Return posts containing products in this market-specific external
              collection.
            example: summer-sale
          required: false
          description: >-
            Return posts containing products in this market-specific external
            collection.
          name: external_collection_id
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 2048
            description: >-
              Opaque cursor returned by the previous page. Keep all other query
              parameters unchanged.
            example: eyJjcmVhdGVkQXQiOiIyMDI2LTA4LTAxVDEwOjAwOjAwLjAwMFoifQ
          required: false
          description: >-
            Opaque cursor returned by the previous page. Keep all other query
            parameters unchanged.
          name: cursor
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
            description: Number of posts to return, from 1 to 50.
            example: 20
          required: false
          description: Number of posts to return, from 1 to 50.
          name: limit
          in: query
      responses:
        '200':
          description: Successful response
          headers:
            Cevoid-Processing-Ms:
              description: End-to-end request processing time in milliseconds
              schema:
                type: string
                example: '12'
            Cevoid-Request-Id:
              description: Request identifier for support and tracing
              schema:
                type: string
                example: req_abc123
            RateLimit-Limit:
              description: Current rate limit bucket size
              schema:
                type: string
                example: '100'
            RateLimit-Remaining:
              description: Remaining requests in the current rate limit window
              schema:
                type: string
                example: '99'
            RateLimit-Reset:
              description: Seconds until the next request token is available
              schema:
                type: integer
                example: 1
            Cache-Control:
              description: >-
                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.
              schema:
                type: string
                example: public, max-age=60, s-maxage=300, stale-while-revalidate=300
            Vary:
              description: Workspace credential headers included in the shared-cache key.
              schema:
                type: string
                example: Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetPostsPage'
        '400':
          description: Bad request
          headers:
            Cevoid-Processing-Ms:
              description: End-to-end request processing time in milliseconds
              schema:
                type: string
                example: '12'
            Cevoid-Request-Id:
              description: Request identifier for support and tracing
              schema:
                type: string
                example: req_abc123
            RateLimit-Limit:
              description: Current rate limit bucket size
              schema:
                type: string
                example: '100'
            RateLimit-Remaining:
              description: Remaining requests in the current rate limit window
              schema:
                type: string
                example: '99'
            RateLimit-Reset:
              description: Seconds until the next request token is available
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          headers:
            Cevoid-Processing-Ms:
              description: End-to-end request processing time in milliseconds
              schema:
                type: string
                example: '12'
            Cevoid-Request-Id:
              description: Request identifier for support and tracing
              schema:
                type: string
                example: req_abc123
            RateLimit-Limit:
              description: Current rate limit bucket size
              schema:
                type: string
                example: '100'
            RateLimit-Remaining:
              description: Remaining requests in the current rate limit window
              schema:
                type: string
                example: '99'
            RateLimit-Reset:
              description: Seconds until the next request token is available
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          headers:
            Cevoid-Processing-Ms:
              description: End-to-end request processing time in milliseconds
              schema:
                type: string
                example: '12'
            Cevoid-Request-Id:
              description: Request identifier for support and tracing
              schema:
                type: string
                example: req_abc123
            RateLimit-Limit:
              description: Current rate limit bucket size
              schema:
                type: string
                example: '100'
            RateLimit-Remaining:
              description: Remaining requests in the current rate limit window
              schema:
                type: string
                example: '99'
            RateLimit-Reset:
              description: Seconds until the next request token is available
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found
          headers:
            Cevoid-Processing-Ms:
              description: End-to-end request processing time in milliseconds
              schema:
                type: string
                example: '12'
            Cevoid-Request-Id:
              description: Request identifier for support and tracing
              schema:
                type: string
                example: req_abc123
            RateLimit-Limit:
              description: Current rate limit bucket size
              schema:
                type: string
                example: '100'
            RateLimit-Remaining:
              description: Remaining requests in the current rate limit window
              schema:
                type: string
                example: '99'
            RateLimit-Reset:
              description: Seconds until the next request token is available
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation error
          headers:
            Cevoid-Processing-Ms:
              description: End-to-end request processing time in milliseconds
              schema:
                type: string
                example: '12'
            Cevoid-Request-Id:
              description: Request identifier for support and tracing
              schema:
                type: string
                example: req_abc123
            RateLimit-Limit:
              description: Current rate limit bucket size
              schema:
                type: string
                example: '100'
            RateLimit-Remaining:
              description: Remaining requests in the current rate limit window
              schema:
                type: string
                example: '99'
            RateLimit-Reset:
              description: Seconds until the next request token is available
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          description: Too many requests
          headers:
            Cevoid-Processing-Ms:
              description: End-to-end request processing time in milliseconds
              schema:
                type: string
                example: '12'
            Cevoid-Request-Id:
              description: Request identifier for support and tracing
              schema:
                type: string
                example: req_abc123
            RateLimit-Limit:
              description: Current rate limit bucket size
              schema:
                type: string
                example: '100'
            RateLimit-Remaining:
              description: Remaining requests in the current rate limit window
              schema:
                type: string
                example: '99'
            RateLimit-Reset:
              description: Seconds until the next request token is available
              schema:
                type: integer
                example: 1
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          description: Internal server error
          headers:
            Cevoid-Processing-Ms:
              description: End-to-end request processing time in milliseconds
              schema:
                type: string
                example: '12'
            Cevoid-Request-Id:
              description: Request identifier for support and tracing
              schema:
                type: string
                example: req_abc123
            RateLimit-Limit:
              description: Current rate limit bucket size
              schema:
                type: string
                example: '100'
            RateLimit-Remaining:
              description: Remaining requests in the current rate limit window
              schema:
                type: string
                example: '99'
            RateLimit-Reset:
              description: Seconds until the next request token is available
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Cevoid-Processing-Ms:
              description: End-to-end request processing time in milliseconds
              schema:
                type: string
                example: '12'
            Cevoid-Request-Id:
              description: Request identifier for support and tracing
              schema:
                type: string
                example: req_abc123
            RateLimit-Limit:
              description: Current rate limit bucket size
              schema:
                type: string
                example: '100'
            RateLimit-Remaining:
              description: Remaining requests in the current rate limit window
              schema:
                type: string
                example: '99'
            RateLimit-Reset:
              description: Seconds until the next request token is available
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    WidgetPostsPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WidgetPost'
        has_more:
          type: boolean
          description: Whether another page is available.
          example: true
        next_cursor:
          type: string
          nullable: true
          description: >-
            Opaque cursor for the next page, or null when this is the final
            page.
          example: eyJwdWJsaXNoZWRBdCI6IjIwMjYtMDgtMDFUMTA6MDA6MDAuMDAwWiJ9
      required:
        - data
        - has_more
        - next_cursor
      example:
        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
    ApiErrorResponse:
      type: object
      properties:
        additional_data:
          type: object
          additionalProperties:
            nullable: true
          description: Optional machine-readable error details.
        status:
          type: integer
          description: HTTP status code.
          example: 404
        code:
          type: string
          description: Stable machine-readable error code.
          example: not_found
        message:
          type: string
          description: Human-readable error description.
          example: Resource not found
        request_id:
          type: string
          description: Request identifier for support and tracing.
          example: req_abc123
      required:
        - status
        - code
        - message
    RateLimitErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ApiErrorResponse'
        - type: object
          properties:
            additional_data:
              type: object
              properties:
                retry_after_seconds:
                  type: integer
                  minimum: 0
              required:
                - retry_after_seconds
              additionalProperties:
                nullable: true
              description: Machine-readable rate-limit details.
          required:
            - additional_data
      example:
        status: 429
        code: rate_limit_exceeded
        message: Rate limit exceeded
        request_id: req_abc123
        additional_data:
          retry_after_seconds: 1
    WidgetPost:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 256
          description: Stable public Post identifier.
          example: pst_summerlook
        type:
          type: string
          enum:
            - IMAGE
            - VIDEO
          description: Post media type.
          example: IMAGE
        media:
          $ref: '#/components/schemas/WidgetPostMedia'
        caption:
          type: string
          description: Public post caption. Omitted when hide_caption is true.
          example: A summer favorite.
        hide_caption:
          type: boolean
          description: Whether clients should hide the caption.
          example: false
        alt:
          type: string
          description: Accessible media description.
          example: Person wearing a beige linen shirt outdoors.
        video_captions:
          type: string
          description: WebVTT captions for video media.
          example: |-
            WEBVTT

            00:00.000 --> 00:02.000
            A summer favorite.
        video_description:
          type: string
          description: Accessible description of video content.
          example: A person turns to show the front and back of a linen shirt.
        source_url:
          type: string
          format: uri
          description: Original public social post URL when available.
          example: https://www.instagram.com/p/example/
        author:
          $ref: '#/components/schemas/WidgetPostAuthor'
        custom_link:
          type: object
          properties:
            url:
              type: string
              format: uri
              example: https://shop.example.com/stories/summer
            title:
              type: string
              example: Summer stories
            description:
              type: string
              example: Explore our summer stories.
            image_url:
              type: string
              format: uri
              example: https://cdn.cevoid.com/stories/summer.jpg
          required:
            - url
          description: Editorial link attached to this post.
          example:
            url: https://shop.example.com/stories/summer
            title: Summer stories
        tagged_products:
          type: array
          items:
            $ref: '#/components/schemas/WidgetPostProduct'
          description: >-
            Shoppable products in the selected market. Products without a
            presentation in that market are omitted.
        published_at:
          type: string
          format: date-time
          description: >-
            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'
      required:
        - id
        - type
        - media
        - hide_caption
        - tagged_products
        - published_at
      example:
        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'
    WidgetPostMedia:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: CDN URL for the post media.
          example: https://cdn.cevoid.com/posts/pst_summerlook.jpg
        thumbnail_url:
          type: string
          format: uri
          description: Smaller preview image when available.
          example: https://cdn.cevoid.com/posts/pst_summerlook-thumbnail.jpg
        sprite_url:
          type: string
          format: uri
          description: Video sprite image for timeline previews when available.
          example: https://cdn.cevoid.com/posts/pst_summerlook-sprite.jpg
        blurhash:
          type: string
          description: BlurHash placeholder for the media asset.
          example: LEHV6nWB2yk8pyo0adR*.7kCMdnj
        aspect_ratio:
          type: number
          minimum: 0
          exclusiveMinimum: true
          description: Media width divided by height.
          example: 0.8
        duration_seconds:
          type: number
          minimum: 0
          description: Video duration in seconds.
          example: 12.5
        has_audio:
          type: boolean
          description: Whether video media includes an audio track.
          example: true
      required:
        - url
    WidgetPostAuthor:
      type: object
      properties:
        name:
          type: string
          description: Public display name selected for the storefront.
          example: '@jane'
        avatar_url:
          type: string
          format: uri
          description: Public profile image URL when available.
          example: https://cdn.cevoid.com/profiles/prf_jane.jpg
      required:
        - name
    WidgetPostProduct:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 256
          description: Stable public Product identifier.
          example: prd_linen_shirt
        title:
          type: string
          description: Market-specific product title.
          example: Linen Shirt
        type:
          type: string
          enum:
            - PRODUCT
            - VARIANT
          example: PRODUCT
        parent_product_id:
          type: string
          minLength: 1
          maxLength: 256
          example: prd_linen_shirt
        availability:
          type: string
          enum:
            - IN_STOCK
            - OUT_OF_STOCK
          example: IN_STOCK
        url:
          type: string
          format: uri
          description: Market-specific storefront URL.
          example: https://shop.example.com/products/linen-shirt
        image_url:
          type: string
          format: uri
          description: Market-specific product image URL.
          example: https://cdn.cevoid.com/products/linen-shirt.jpg
        price:
          anyOf:
            - type: object
              properties:
                currency:
                  type: string
                min_amount:
                  type: number
                  minimum: 0
                max_amount:
                  type: number
                  minimum: 0
              required:
                - currency
                - min_amount
                - max_amount
            - type: object
              properties:
                currency:
                  type: string
                amount:
                  type: number
                  minimum: 0
                sale_amount:
                  type: number
                  minimum: 0
              required:
                - currency
                - amount
          description: >-
            Product price range or exact variant price in the selected market.
            Omitted when the market hides prices.
          example:
            currency: SEK
            min_amount: 59.95
            max_amount: 79.95
        x:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Normalized horizontal hotspot position. Omitted together with y when
            no valid position is stored.
          example: 0.35
        'y':
          type: number
          minimum: 0
          maximum: 1
          description: Normalized vertical hotspot position.
          example: 0.65
      required:
        - id
        - title
        - type
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Cevoid publishable key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.