{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Cevoid Public API",
    "description": "Public API for accessing Cevoid user-generated content and loyalty data. Use this API to retrieve posts, members, markets, and other data from your Cevoid account.",
    "contact": {
      "name": "Cevoid Support",
      "url": "https://cevoid.com/support",
      "email": "support@cevoid.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.cevoid.com",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Posts",
      "description": "User-generated content posts operations"
    },
    {
      "name": "Members",
      "description": "Loyalty program members operations"
    },
    {
      "name": "Markets",
      "description": "Market and localization operations"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "schemas": {
      "PostsResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Total number of items"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL for next page"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PostWithLabels"
            }
          }
        },
        "required": [
          "count",
          "next",
          "nodes"
        ]
      },
      "PostWithLabels": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Post"
          },
          {
            "type": "object",
            "properties": {
              "labels": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Label ID. Use this value in label filters or /v1/labels/{id}/posts.",
                      "example": "507f1f77bcf86cd799439011"
                    },
                    "name": {
                      "type": "string",
                      "nullable": true,
                      "description": "Stored label name, or null if unnamed. Not translated by the market parameter.",
                      "example": "Summer"
                    }
                  },
                  "required": [
                    "id",
                    "name"
                  ]
                },
                "description": "Included only with include=labels. All available labels attached to the post, in stored order, regardless of label filters. Empty when no labels resolve; removed or inaccessible labels are omitted."
              }
            }
          }
        ]
      },
      "PostOrigin": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Source platform where the post originated (e.g., \"instagram\", \"tiktok\", \"upload\", \"manual\")",
            "example": "instagram"
          }
        },
        "required": [
          "type"
        ]
      },
      "Media": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "URL or CDN path to the media file (image or video)",
            "example": "https://cdn.cevoid.com/media/posts/abc123.jpg"
          },
          "hash": {
            "type": "string",
            "description": "Blurhash string for generating blur placeholder images while the media is loading. Use with the blurhash library to decode.",
            "example": "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
          },
          "filename": {
            "type": "string",
            "description": "Original filename when the media was uploaded, preserving the user's original file naming",
            "example": "summer-vacation-photo.jpg"
          }
        },
        "required": [
          "location"
        ]
      },
      "TaggedProduct": {
        "type": "object",
        "properties": {
          "x": {
            "type": "number",
            "description": "Horizontal position coordinate (0-1) where the product is tagged on the image/video",
            "example": 0.35
          },
          "y": {
            "type": "number",
            "description": "Vertical position coordinate (0-1) where the product is tagged on the image/video",
            "example": 0.65
          },
          "product": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique identifier for the product in the Cevoid system",
                "example": "prod_abc123"
              },
              "title": {
                "type": "string",
                "description": "Display name/title of the product as shown to customers",
                "example": "Wireless Bluetooth Headphones"
              },
              "price": {
                "type": "object",
                "properties": {
                  "price": {
                    "type": "number",
                    "description": "Regular price of the product in the specified currency",
                    "example": 99.99
                  },
                  "currency": {
                    "type": "string",
                    "description": "ISO 4217 currency code for the product pricing",
                    "example": "USD"
                  },
                  "salePrice": {
                    "type": "number",
                    "description": "Discounted sale price if the product is currently on sale",
                    "example": 79.99
                  }
                },
                "description": "Pricing information for the product including regular price, currency, and sale pricing"
              },
              "category": {
                "type": "string",
                "description": "Product category or classification for organizational purposes",
                "example": "Electronics > Audio > Headphones"
              },
              "media": {
                "$ref": "#/components/schemas/Media"
              },
              "handle": {
                "type": "string",
                "description": "URL-friendly identifier for the product, typically used in product page URLs",
                "example": "wireless-bluetooth-headphones"
              },
              "url": {
                "type": "string",
                "description": "Full URL to the product page on the e-commerce store",
                "example": "https://mystore.com/products/wireless-bluetooth-headphones"
              },
              "developmentUrl": {
                "type": "string",
                "description": "Development/staging URL for the product page, used for testing purposes",
                "example": "https://dev.mystore.com/products/wireless-bluetooth-headphones"
              },
              "sku": {
                "type": "string",
                "description": "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"
              },
              "mpn": {
                "type": "string",
                "description": "Manufacturer part number. For grouped products this is typically the style-level number and is stable across sizes. Omitted when absent.",
                "example": "693903"
              },
              "gtin": {
                "type": "string",
                "description": "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"
              }
            },
            "required": [
              "id",
              "title",
              "handle"
            ],
            "description": "Complete product information including pricing, media, and links"
          }
        },
        "required": [
          "x",
          "y",
          "product"
        ]
      },
      "UploadedBy": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "description": "Username or display name of the user who uploaded/created this post",
            "example": "john_doe_photography"
          },
          "email": {
            "type": "string",
            "description": "Email address of the member who submitted this post. Only included for inbox posts.",
            "example": "sarah@example.com"
          },
          "image": {
            "type": "object",
            "properties": {
              "hash": {
                "type": "string",
                "description": "Unique content hash for the user's profile image",
                "example": "sha256:b2c3d4e5f6a7..."
              },
              "filename": {
                "type": "string",
                "description": "Original filename of the user's profile image",
                "example": "profile-pic.jpg"
              },
              "location": {
                "type": "string",
                "description": "URL or CDN path to the user's profile image",
                "example": "https://cdn.cevoid.com/profiles/user123/avatar.jpg"
              }
            },
            "required": [
              "hash",
              "filename",
              "location"
            ],
            "description": "Profile image information for the user who uploaded this post"
          }
        },
        "required": [
          "username"
        ]
      },
      "Post": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the post within the Cevoid system",
            "example": "post_abc123def456"
          },
          "origin": {
            "$ref": "#/components/schemas/PostOrigin"
          },
          "alt": {
            "type": "string",
            "description": "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"
          },
          "videoCaptions": {
            "type": "string",
            "description": "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."
          },
          "videoDescription": {
            "type": "string",
            "description": "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"
          },
          "instagramUrl": {
            "type": "string",
            "description": "Original Instagram post URL if this content was imported from Instagram",
            "example": "https://www.instagram.com/p/ABC123DEF456/"
          },
          "type": {
            "type": "string",
            "description": "Media type of the post content, typically \"IMAGE\" for photos or \"VIDEO\" for video content",
            "example": "IMAGE"
          },
          "fromInstagram": {
            "type": "boolean",
            "description": "Indicates whether this post was imported from Instagram through social media integration",
            "example": true
          },
          "addedByCompany": {
            "type": "boolean",
            "description": "Indicates whether this post was uploaded directly by the company/brand rather than user-generated content",
            "example": false
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp indicating when the post was first created or imported into the Cevoid system",
            "example": "2024-01-15T10:30:00.000Z"
          },
          "instagramDate": {
            "type": "string",
            "description": "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"
          },
          "media": {
            "$ref": "#/components/schemas/Media"
          },
          "comment": {
            "type": "string",
            "description": "Caption or comment text associated with the post, often containing hashtags, mentions, and descriptions",
            "example": "Perfect day at the beach! ☀️ #SummerVibes #BeachLife #Sunglasses"
          },
          "taggedProducts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaggedProduct"
            },
            "description": "Array of products that have been tagged or featured in this post, including their position coordinates and product details",
            "example": [
              {
                "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": {
            "type": "boolean",
            "description": "Setting to control whether the post caption should be hidden when displaying the post in galleries or widgets",
            "example": false
          },
          "uploadedBy": {
            "$ref": "#/components/schemas/UploadedBy"
          }
        },
        "required": [
          "id",
          "createdAt",
          "media",
          "taggedProducts"
        ]
      },
      "ErrorResponse": {
        "type": "string"
      },
      "UnauthorizedResponse": {
        "type": "string",
        "enum": [
          "No valid API key provided"
        ]
      },
      "InternalServerErrorResponse": {
        "type": "string",
        "enum": [
          "Something went wrong"
        ]
      },
      "PostResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the post within the Cevoid system",
            "example": "post_abc123def456"
          },
          "origin": {
            "$ref": "#/components/schemas/PostOrigin"
          },
          "alt": {
            "type": "string",
            "description": "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"
          },
          "videoCaptions": {
            "type": "string",
            "description": "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."
          },
          "videoDescription": {
            "type": "string",
            "description": "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"
          },
          "instagramUrl": {
            "type": "string",
            "description": "Original Instagram post URL if this content was imported from Instagram",
            "example": "https://www.instagram.com/p/ABC123DEF456/"
          },
          "type": {
            "type": "string",
            "description": "Media type of the post content, typically \"IMAGE\" for photos or \"VIDEO\" for video content",
            "example": "IMAGE"
          },
          "fromInstagram": {
            "type": "boolean",
            "description": "Indicates whether this post was imported from Instagram through social media integration",
            "example": true
          },
          "addedByCompany": {
            "type": "boolean",
            "description": "Indicates whether this post was uploaded directly by the company/brand rather than user-generated content",
            "example": false
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp indicating when the post was first created or imported into the Cevoid system",
            "example": "2024-01-15T10:30:00.000Z"
          },
          "instagramDate": {
            "type": "string",
            "description": "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"
          },
          "media": {
            "$ref": "#/components/schemas/Media"
          },
          "comment": {
            "type": "string",
            "description": "Caption or comment text associated with the post, often containing hashtags, mentions, and descriptions",
            "example": "Perfect day at the beach! ☀️ #SummerVibes #BeachLife #Sunglasses"
          },
          "taggedProducts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaggedProduct"
            },
            "description": "Array of products that have been tagged or featured in this post, including their position coordinates and product details",
            "example": [
              {
                "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": {
            "type": "boolean",
            "description": "Setting to control whether the post caption should be hidden when displaying the post in galleries or widgets",
            "example": false
          },
          "uploadedBy": {
            "$ref": "#/components/schemas/UploadedBy"
          }
        },
        "required": [
          "id",
          "createdAt",
          "media",
          "taggedProducts"
        ]
      },
      "PostsByGalleryResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Total number of items"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL for next page"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Post"
            }
          }
        },
        "required": [
          "count",
          "next",
          "nodes"
        ]
      },
      "PostsByProductResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Total number of items"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL for next page"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Post"
            }
          }
        },
        "required": [
          "count",
          "next",
          "nodes"
        ]
      },
      "PostsByCollectionResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Total number of items"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL for next page"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Post"
            }
          }
        },
        "required": [
          "count",
          "next",
          "nodes"
        ]
      },
      "PostsByMemberResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Total number of items"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL for next page"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Post"
            }
          }
        },
        "required": [
          "count",
          "next",
          "nodes"
        ]
      },
      "PostsByLabelResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Total number of items"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL for next page"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Post"
            }
          }
        },
        "required": [
          "count",
          "next",
          "nodes"
        ]
      },
      "InboxResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Total number of items"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL for next page"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Post"
            }
          }
        },
        "required": [
          "count",
          "next",
          "nodes"
        ]
      },
      "MarketsResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Total number of items"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL for next page"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Market"
            }
          }
        },
        "required": [
          "count",
          "next",
          "nodes"
        ]
      },
      "Market": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the market within the Cevoid system",
            "example": "market_us_123abc"
          },
          "shortId": {
            "type": "string",
            "description": "Shortened, human-readable identifier for the market, typically used in URLs and API calls",
            "example": "us"
          },
          "title": {
            "type": "string",
            "description": "Display name of the market, typically representing the country or region",
            "example": "United States"
          },
          "customId": {
            "type": "string",
            "description": "Custom identifier for the market, alternative to shortId",
            "example": "us-market"
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code representing the geographic market location",
            "example": "US"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code used for pricing and transactions within this market",
            "example": "USD"
          },
          "language": {
            "type": "string",
            "description": "ISO 639-1 language code representing the primary language for content and communications in this market",
            "example": "en"
          },
          "domain": {
            "type": "string",
            "description": "Primary domain URL or website associated with this market, used for e-commerce store integration",
            "example": "https://store.example.com"
          },
          "default": {
            "type": "boolean",
            "description": "Indicates whether this market serves as the default/fallback market when no specific market is selected",
            "example": true
          },
          "settings": {
            "nullable": true,
            "description": "Market-specific configuration and settings object",
            "example": {}
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp indicating when this market was first created in the system",
            "example": "2024-01-10T08:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "description": "ISO 8601 timestamp indicating when this market was last updated",
            "example": "2024-01-15T12:45:30.000Z"
          }
        },
        "required": [
          "id",
          "shortId",
          "title",
          "country",
          "currency",
          "language",
          "domain",
          "default",
          "createdAt",
          "updatedAt"
        ]
      },
      "MarketResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the market within the Cevoid system",
            "example": "market_us_123abc"
          },
          "shortId": {
            "type": "string",
            "description": "Shortened, human-readable identifier for the market, typically used in URLs and API calls",
            "example": "us"
          },
          "title": {
            "type": "string",
            "description": "Display name of the market, typically representing the country or region",
            "example": "United States"
          },
          "customId": {
            "type": "string",
            "description": "Custom identifier for the market, alternative to shortId",
            "example": "us-market"
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code representing the geographic market location",
            "example": "US"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code used for pricing and transactions within this market",
            "example": "USD"
          },
          "language": {
            "type": "string",
            "description": "ISO 639-1 language code representing the primary language for content and communications in this market",
            "example": "en"
          },
          "domain": {
            "type": "string",
            "description": "Primary domain URL or website associated with this market, used for e-commerce store integration",
            "example": "https://store.example.com"
          },
          "default": {
            "type": "boolean",
            "description": "Indicates whether this market serves as the default/fallback market when no specific market is selected",
            "example": true
          },
          "settings": {
            "nullable": true,
            "description": "Market-specific configuration and settings object",
            "example": {}
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp indicating when this market was first created in the system",
            "example": "2024-01-10T08:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "description": "ISO 8601 timestamp indicating when this market was last updated",
            "example": "2024-01-15T12:45:30.000Z"
          }
        },
        "required": [
          "id",
          "shortId",
          "title",
          "country",
          "currency",
          "language",
          "domain",
          "default",
          "createdAt",
          "updatedAt"
        ]
      },
      "MarketNotFoundResponse": {
        "type": "string",
        "enum": [
          "Could not find market"
        ]
      },
      "MembersResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "number",
            "description": "Total number of items"
          },
          "next": {
            "type": "string",
            "nullable": true,
            "description": "URL for next page"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Member"
            }
          }
        },
        "required": [
          "count",
          "next",
          "nodes"
        ]
      },
      "Member": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the member within the Cevoid system",
            "example": "member_abc123def456"
          },
          "shortId": {
            "type": "string",
            "description": "Shortened, human-readable identifier for the member, often used in URLs and public references",
            "example": "mem_5a8b9c"
          },
          "name": {
            "type": "string",
            "description": "Display name or full name of the member as provided during registration or profile updates",
            "example": "Sarah Johnson"
          },
          "email": {
            "type": "string",
            "description": "Email address associated with the member account, used for communication and authentication",
            "example": "sarah.johnson@example.com"
          },
          "avatarUrl": {
            "type": "string",
            "description": "URL to the member's profile picture or avatar image",
            "example": "https://cdn.cevoid.com/avatars/member123/profile.jpg"
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code representing the member's country of residence",
            "example": "US"
          },
          "language": {
            "type": "string",
            "description": "ISO 639-1 language code representing the member's preferred language for communications",
            "example": "en"
          },
          "location": {
            "type": "string",
            "description": "Geographic location information such as city, state, or region provided by the member",
            "example": "San Francisco, CA"
          },
          "socialInstagramHandle": {
            "type": "string",
            "description": "Instagram username/handle associated with the member's social media account, without the @ symbol",
            "example": "sarah.lifestyle"
          },
          "bio": {
            "type": "string",
            "description": "Biography or description provided by the member",
            "example": "Lifestyle blogger and photography enthusiast"
          },
          "notes": {
            "type": "string",
            "description": "Internal notes about the member for company reference",
            "example": "VIP customer, prefers email communication"
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp indicating when the member account was first created in the system",
            "example": "2024-01-15T09:30:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "description": "ISO 8601 timestamp indicating when the member was last updated",
            "example": "2024-01-20T14:22:15.000Z"
          }
        },
        "required": [
          "id",
          "shortId",
          "createdAt",
          "updatedAt"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/v1/posts": {
      "get": {
        "summary": "List posts",
        "description": "Returns approved posts with optional label filtering and label details.",
        "tags": [
          "Posts"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 25,
              "default": 25,
              "description": "Max value for limit is 25",
              "example": 10
            },
            "required": false,
            "description": "Max value for limit is 25",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "minimum": 0,
              "default": 0,
              "description": "Number of items to skip",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip",
            "name": "skip",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Market ID or shortId for localized content",
              "example": "us"
            },
            "required": false,
            "description": "Market ID or shortId for localized content",
            "name": "market",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "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\"]}]"
            },
            "required": false,
            "description": "JSON string array of filter criteria. See Core Concepts → Filtering for detailed filter structure and supported operators.",
            "name": "filter",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated relationships to include in each post. Supported values: `labels` (adds each label’s `id` and `name`). See [Includes](/api-reference/includes) for usage and response behavior. Omit to keep the default response. Unsupported or empty values return 400.",
              "example": "labels"
            },
            "required": false,
            "description": "Comma-separated relationships to include in each post. Supported values: `labels` (adds each label’s `id` and `name`). See [Includes](/api-reference/includes) for usage and response behavior. Omit to keep the default response. Unsupported or empty values return 400.",
            "name": "include",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/posts/{id}": {
      "get": {
        "summary": "Get post by ID",
        "description": "Retrieve a single post by its ID",
        "tags": [
          "Posts"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Unique identifier",
              "example": "507f1f77bcf86cd799439011"
            },
            "required": true,
            "description": "Unique identifier",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "description": "Market ID or shortId for localized content",
              "example": "us"
            },
            "required": false,
            "description": "Market ID or shortId for localized content",
            "name": "market",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/galleries/{id}/posts": {
      "get": {
        "summary": "Get posts from a specific gallery",
        "description": "Retrieve all posts belonging to a specific gallery",
        "tags": [
          "Posts"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Gallery shortId",
              "example": "gallery123"
            },
            "required": true,
            "description": "Gallery shortId",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 25,
              "default": 25,
              "description": "Max value for limit is 25",
              "example": 10
            },
            "required": false,
            "description": "Max value for limit is 25",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "minimum": 0,
              "default": 0,
              "description": "Number of items to skip",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip",
            "name": "skip",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Market ID or shortId for localized content",
              "example": "us"
            },
            "required": false,
            "description": "Market ID or shortId for localized content",
            "name": "market",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostsByGalleryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/products/{id}/posts": {
      "get": {
        "summary": "Get posts tagged with a specific product",
        "description": "Retrieve all posts that have been tagged with a specific product",
        "tags": [
          "Posts"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "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"
            },
            "required": true,
            "description": "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",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 25,
              "default": 25,
              "description": "Max value for limit is 25",
              "example": 10
            },
            "required": false,
            "description": "Max value for limit is 25",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "minimum": 0,
              "default": 0,
              "description": "Number of items to skip",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip",
            "name": "skip",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Market ID or shortId for localized content",
              "example": "us"
            },
            "required": false,
            "description": "Market ID or shortId for localized content",
            "name": "market",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "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\"]}]"
            },
            "required": false,
            "description": "JSON string array of filter criteria. See Core Concepts → Filtering for detailed filter structure and supported operators.",
            "name": "filter",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "external_id",
                "mpn"
              ],
              "description": "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.",
              "example": "mpn"
            },
            "required": false,
            "description": "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.",
            "name": "id_type",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostsByProductResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/collections/{id}/posts": {
      "get": {
        "summary": "Get posts in a collection by ID",
        "description": "Retrieve posts that contain products in the specified collection (e.g. Shopify collection handle or external ID)",
        "tags": [
          "Posts"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Collection ID (e.g. Shopify collection handle or external ID)",
              "example": "summer-sale"
            },
            "required": true,
            "description": "Collection ID (e.g. Shopify collection handle or external ID)",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 25,
              "default": 25,
              "description": "Max value for limit is 25",
              "example": 10
            },
            "required": false,
            "description": "Max value for limit is 25",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "minimum": 0,
              "default": 0,
              "description": "Number of items to skip",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip",
            "name": "skip",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Market ID or shortId for localized content",
              "example": "us"
            },
            "required": false,
            "description": "Market ID or shortId for localized content",
            "name": "market",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostsByCollectionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/members/{id}/posts": {
      "get": {
        "summary": "Get posts from a specific member",
        "description": "Retrieve all posts created by a specific member",
        "tags": [
          "Posts"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Member shortId",
              "example": "member123"
            },
            "required": true,
            "description": "Member shortId",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 25,
              "default": 25,
              "description": "Max value for limit is 25",
              "example": 10
            },
            "required": false,
            "description": "Max value for limit is 25",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "minimum": 0,
              "default": 0,
              "description": "Number of items to skip",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip",
            "name": "skip",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Market ID or shortId for localized content",
              "example": "us"
            },
            "required": false,
            "description": "Market ID or shortId for localized content",
            "name": "market",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostsByMemberResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/labels/{id}/posts": {
      "get": {
        "summary": "Get posts with a specific label",
        "description": "Retrieve all posts that have been assigned a specific label",
        "tags": [
          "Posts"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Unique identifier",
              "example": "507f1f77bcf86cd799439011"
            },
            "required": true,
            "description": "Unique identifier",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 25,
              "default": 25,
              "description": "Max value for limit is 25",
              "example": 10
            },
            "required": false,
            "description": "Max value for limit is 25",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "minimum": 0,
              "default": 0,
              "description": "Number of items to skip",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip",
            "name": "skip",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Market ID or shortId for localized content",
              "example": "us"
            },
            "required": false,
            "description": "Market ID or shortId for localized content",
            "name": "market",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostsByLabelResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inbox": {
      "get": {
        "summary": "Get inbox posts",
        "description": "Retrieve pending posts awaiting moderation (inbox). Each post includes the email of the member who submitted it in the uploadedBy field.",
        "tags": [
          "Inbox"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 25,
              "default": 25,
              "description": "Max value for limit is 25",
              "example": 10
            },
            "required": false,
            "description": "Max value for limit is 25",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "minimum": 0,
              "default": 0,
              "description": "Number of items to skip",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip",
            "name": "skip",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InboxResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/markets": {
      "get": {
        "summary": "Get markets",
        "description": "Retrieve all available markets for the company",
        "tags": [
          "Markets"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 25,
              "default": 25,
              "description": "Max value for limit is 25",
              "example": 10
            },
            "required": false,
            "description": "Max value for limit is 25",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "minimum": 0,
              "default": 0,
              "description": "Number of items to skip",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip",
            "name": "skip",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/markets/{id}": {
      "get": {
        "summary": "Get market by ID",
        "description": "Retrieve a specific market by its ID or shortId",
        "tags": [
          "Markets"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Market ID or shortId",
              "example": "us"
            },
            "required": true,
            "description": "Market ID or shortId",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketNotFoundResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/members": {
      "get": {
        "summary": "Get members",
        "description": "Retrieve all members with optional pagination",
        "tags": [
          "Members"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 25,
              "default": 25,
              "description": "Max value for limit is 25",
              "example": 10
            },
            "required": false,
            "description": "Max value for limit is 25",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "number",
              "nullable": true,
              "minimum": 0,
              "default": 0,
              "description": "Number of items to skip",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip",
            "name": "skip",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Market ID or shortId for localized content",
              "example": "us"
            },
            "required": false,
            "description": "Market ID or shortId for localized content",
            "name": "market",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MembersResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}