Testing archive/unarchive campaigns
","startDate":"2025-04-09T13:58:16.362Z","endDate":null,"maxParticipants":10000,"hero":[{"url":"https://res.cloudinary.com/dglfgrzex/image/upload/v1744207053/launchpad-poc/cm8qdybu50000l80cq928qdf7/campaigns/cm99ztz8x0001jm0d55tvj188/wjtnrizk51ciun6cegwb.png","alt":"Campaign Image: https://res.cloudinary.com/dglfgrzex/image/upload/v1744207053/launchpad-poc/cm8qdybu50000l80cq928qdf7/campaigns/cm99ztz8x0001jm0d55tvj188/wjtnrizk51ciun6cegwb.png"}],"video":null,"showInstructions":true,"showLeaderboard":true,"createdAt":"2025-04-09T13:57:11.986Z","publishedAt":"2025-04-09T13:58:16.362Z","updatedAt":"2025-10-01T20:05:51.424Z","contractId":550,"logo":null,"creatorId":"cm8qe0dys0000kw0c4j6adlkk","rateLimit":0,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"archivedAt":null,"attributes":[],"questions":[{"id":280,"organizationId":"cly0d950o000310tjxcorg123","campaignId":"cm99ztz8x0001jm0d55tvj188","type":"MULTIPLE_CHOICE","title":"Test Question","options":[{"value":"Choice A"},{"value":"Choice B"}],"createdAt":"2025-04-09T13:58:11.716Z","media":null}],"contract":{"id":550,"organizationId":"cly0d950o000310tjxcorg123","name":"Archive Campaign Test 4.9.25","symbol":"ARCHIVE_CAMPAIGN_TEST_4_9_25","proxyAddress":"0xe7976314948c43b093F3FCB45a8d3A5E923CB53f","implementationAddress":"0xe911d9502D752Dc2329F0E6D5726D42bfAcD99f6","metadataIpfsHash":"bafybeiavuq3lspchkkjpkkknqnvp24g5tcp3vrvwpzovbxht7w57crirpy","maxSupply":10000,"transferable":false,"points":0,"chainId":84532,"createdAt":"2025-04-09T13:58:15.474Z","updatedAt":"2025-04-09T13:58:44.643Z","abiId":1,"metadata":{"id":531,"organizationId":"cly0d950o000310tjxcorg123","nftContractId":550,"imageUrl":"https://res.cloudinary.com/dglfgrzex/image/upload/v1744207053/launchpad-poc/cm8qdybu50000l80cq928qdf7/campaigns/cm99ztz8x0001jm0d55tvj188/wjtnrizk51ciun6cegwb.png","description":"Testing archive/unarchive campaigns
","attributes":[{"value":"momo727","trait_type":"Brand"},{"value":"Archive Campaign Test 4.9.25","trait_type":"Collection"}],"externalUrl":null,"animationUrl":null}},"reward":null}}}}}}}}}},"/creator/id/{creatorId}/campaigns/titles":{"get":{"summary":"List creator campaign titles","description":"Returns campaign titles for the specified Merchant.","tags":["Campaigns"],"operationId":"listTitles","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Campaign titles fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaign titles","value":{"campaigns":[{"id":"cm3campaignid123","title":"Fan Survey Campaign"},{"id":"cm3campaignid456","title":"Product Feedback"}]}}}}}}}}},"/creator/id/{creatorId}/campaigns":{"get":{"summary":"List creator campaigns","description":"Returns campaigns for the specified Merchant with optional status filtering and search.","tags":["Campaigns"],"operationId":"list","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"query","name":"statuses","schema":{"description":"Filter campaigns by one or more statuses","example":["PUBLISHED","DRAFT"],"anyOf":[{"type":"string","enum":["DRAFT","SUBMITTED","APPROVED","DENIED","PUBLISHED","ENDED","PAUSED","ARCHIVED"]},{"type":"array","items":{"type":"string","enum":["DRAFT","SUBMITTED","APPROVED","DENIED","PUBLISHED","ENDED","PAUSED","ARCHIVED"]}}]},"description":"Filter campaigns by one or more statuses"},{"in":"query","name":"search","schema":{"description":"Full-text search string applied to campaign titles","example":"campaign title","type":"string"},"description":"Full-text search string applied to campaign titles"}],"responses":{"200":{"description":"Merchant campaigns fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaigns list","value":{"data":[{"id":"cm3campaignid123","organizationId":"cly0d950o000310tjxcorg123","title":"Fan Survey Campaign","status":"PUBLISHED","creatorId":"cm3creatorid456","createdAt":"2025-09-01T00:00:00.000Z","updatedAt":"2025-09-15T00:00:00.000Z","hero":{},"totalVotes":250,"pointStats":null,"participantsCount":230,"reward":null,"description":"Share your feedback with us!","publishedAt":"2025-09-01T10:00:00.000Z","startDate":"2025-09-01T10:00:00.000Z","endDate":null,"maxParticipants":null,"logo":"https://example.com/campaign-logo.jpg","video":null,"showInstructions":true,"showLeaderboard":true,"rateLimit":0,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"type":"SURVEY","contractId":null,"archivedAt":null}],"page":1,"limit":20,"total":1}}}}}}}}},"/creator/id/{creatorId}/campaigns/analytics/participants/count":{"get":{"summary":"Get total campaign participants for a creator","description":"Returns the total participant count across campaigns for the specified Merchant.","tags":["Merchant Campaigns Analytics"],"operationId":"listParticipantsCount","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Total participant count fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Participant count","value":{"totalParticipants":1256,"last24HoursParticipantsGrowth":42}}}}}}}}},"/creator/id/{creatorId}/campaigns/latest":{"get":{"summary":"Get creator latest campaign","description":"Returns the latest campaign for the specified Merchant, optionally filtered by status.","tags":["Campaigns"],"operationId":"listLatest","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"query","name":"statuses","schema":{"description":"Optional list of statuses to filter the latest campaign","example":["PUBLISHED","DRAFT"],"type":"array","items":{"type":"string","enum":["DRAFT","SUBMITTED","APPROVED","DENIED","PUBLISHED","ENDED","PAUSED","ARCHIVED"]}},"description":"Optional list of statuses to filter the latest campaign"}],"responses":{"200":{"description":"Latest Merchant campaign fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Latest campaign","value":{"id":"cm3campaignid123","organizationId":"cly0d950o000310tjxcorg123","title":"Latest Campaign","status":"PUBLISHED","creatorId":"cm3creatorid456","createdAt":"2025-09-20T00:00:00.000Z","updatedAt":"2025-09-25T00:00:00.000Z","hero":{},"totalVotes":350,"pointStats":null,"participantsCount":320,"reward":null,"description":"Latest campaign description","publishedAt":"2025-09-20T10:00:00.000Z","startDate":"2025-09-20T10:00:00.000Z","endDate":null,"maxParticipants":null,"logo":"https://example.com/campaign-logo.jpg","video":null,"showInstructions":true,"showLeaderboard":true,"rateLimit":0,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"type":"SURVEY","contractId":null,"archivedAt":null}}}}}}}}},"/creator/id/{creatorId}/nft-rewards":{"get":{"summary":"List creator NFT rewards","description":"Retrieve all NFT rewards for a specific Merchant","tags":["Merchant NFT Rewards"],"operationId":"listNftRewards","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Successfully retrieved NFT rewards","content":{"application/json":{"examples":{"success":{"summary":"NFT rewards list","value":[{"id":"cm0bjzgo30004hz1iwbc75dpi","organizationId":"cly0d950o000310tjxcorg123","status":"PUBLISHED","contractId":142,"creatorId":"clxueqqth000084u356vmxeik","airdropId":null,"createdAt":"2024-08-26T22:11:45.313Z","publishedAt":"2024-08-26T22:12:27.632Z","type":"FREE_PRODUCT","source":"EARNED","conditions":[{"id":19,"organizationId":"cly0d950o000310tjxcorg123","nftRewardId":"cm0bjzgo30004hz1iwbc75dpi","type":"FANS","parameters":[]}],"contract":{"id":142,"organizationId":"cly0d950o000310tjxcorg123","name":"drag and drop","symbol":"DRAG_AND_DROP","proxyAddress":"0xA3d0479Ae8E2d9C222dd3133AA9F897C7fE51F4a","implementationAddress":"0x966dd6Ee2C089eF30b494c614CFf350F7f37980c","metadataIpfsHash":null,"maxSupply":0,"transferable":false,"points":0,"chainId":84532,"createdAt":"2024-08-26T22:12:23.124Z","updatedAt":"2024-08-26T22:12:59.128Z","abiId":4,"metadata":{"id":123,"organizationId":"cly0d950o000310tjxcorg123","nftContractId":142,"imageUrl":"ipfs://QmXVWgqwinhs7meQPUzenm5LLPDxGNLuuCW7vTstQmgY7F/image.png","description":"drag and drop","attributes":[{"value":"Patryk","trait_type":"Brand"}],"externalUrl":"https://app-feature.kiki.world/reward/cm0bjzgo30004hz1iwbc75dpi","animationUrl":null}},"genericRewardDetails":{"id":"cm0bjzp7j0006hz1iecfv4e2p","organizationId":"cly0d950o000310tjxcorg123","rewardId":"cm0bjzgo30004hz1iwbc75dpi","name":"face wash","moreInfo":"more details"}}]}}}}}}}},"/creator/id/{creatorId}/nft-rewards/redeemed":{"get":{"summary":"Get creator NFT rewards redeemed count","description":"Retrieve the count of redeemed NFT rewards for a specific Merchant","tags":["Merchant NFT Rewards"],"operationId":"listNftRewardsRedeemed","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Successfully retrieved redeemed NFT rewards count","content":{"application/json":{"examples":{"success":{"summary":"Redeemed count","value":{"totalRedeemed":342,"redeemedLast24Hours":15}}}}}}}}},"/creator/id/{creatorId}/dashboard/rewards":{"get":{"summary":"Get creator rewards dashboard","description":"Retrieve rewards dashboard data and analytics for a specific Merchant","tags":["Merchant Dashboard"],"operationId":"listRewards","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Successfully retrieved rewards dashboard data","content":{"application/json":{"examples":{"success":{"summary":"Rewards dashboard","value":{"airdrops":[{"id":"cm3airdropid123","name":"VIP Member Airdrop","rewardType":"POINTS","conditionType":"FANS","imageUrl":"https://example.com/airdrop.jpg","chainId":8453,"proxyAddress":"0x1234567890abcdef","airdropId":123,"redeemedCount":42,"uniqueUsersCount":38}],"earnedRewards":[{"id":"cm3rewardid456","name":"Engagement Reward","status":"PUBLISHED","rewardType":"POINTS","conditionType":"PARTICIPATED_IN_CAMPAIGN_POINTS","imageUrl":"https://example.com/reward.jpg","chainId":8453,"proxyAddress":"0xabcdef1234567890","redeemedCount":85,"uniqueUsersCount":72}],"latestAirdrop":{"id":"cm3airdropid123","name":"VIP Member Airdrop","rewardType":"POINTS","conditionType":"FANS","imageUrl":"https://example.com/airdrop.jpg","chainId":8453,"proxyAddress":"0x1234567890abcdef","airdropId":123,"redeemedCount":42,"uniqueUsersCount":38},"latestEarnedReward":{"id":"cm3rewardid456","name":"Engagement Reward","status":"PUBLISHED","rewardType":"POINTS","conditionType":"PARTICIPATED_IN_CAMPAIGN_POINTS","imageUrl":"https://example.com/reward.jpg","chainId":8453,"proxyAddress":"0xabcdef1234567890","redeemedCount":85,"uniqueUsersCount":72},"totalAirdrops":5,"totalEarnedRewards":8,"totalRedeemed":342,"redeemedLast24Hours":15}}}}}}}}},"/creator/id/{creatorId}/dashboard/fans":{"get":{"summary":"Get creator fans dashboard","description":"Retrieve fan dashboard data and analytics for a specific Merchant","tags":["Merchant Dashboard"],"operationId":"listFans","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Successfully retrieved fans dashboard data","content":{"application/json":{"examples":{"success":{"summary":"Fans dashboard","value":{"topFollowers":[{"score":95.5,"id":"cm3userid123","username":"superfan","avatarUrl":"https://example.com/avatar.jpg","totalMoments":42,"nftRedemptions":8,"nftCount":12,"totalPoints":5000}],"followers":[{"id":"cm3userid123","organizationId":"cly0d950o000310tjxcorg123","username":"superfan","displayName":null,"email":"superfan@example.com","emailVerified":true,"avatarUrl":"https://example.com/avatar.jpg","city":"San Francisco","state":"CA","bio":"Big fan!","createdAt":"2025-01-15T00:00:00.000Z","updatedAt":"2025-09-01T00:00:00.000Z","streamChatToken":null,"roles":[]}],"totalFollowers":1250}}}}}}}}},"/creator/id/{creatorId}/dashboard/campaigns":{"get":{"summary":"Get creator campaigns dashboard","description":"Retrieve campaign dashboard data and analytics for a specific Merchant","tags":["Merchant Dashboard"],"operationId":"listCampaigns","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Successfully retrieved campaigns dashboard data","content":{"application/json":{"examples":{"success":{"summary":"Campaigns dashboard","value":{"activeCampaigns":[{"id":"cm3campaignid123","organizationId":"cly0d950o000310tjxcorg123","title":"Fan Survey Campaign","status":"PUBLISHED","creatorId":"cm3creatorid456","createdAt":"2025-09-01T00:00:00.000Z","updatedAt":"2025-09-15T00:00:00.000Z","hero":{},"totalVotes":350,"pointStats":null,"participantsCount":320,"reward":null,"description":"Share your feedback!","publishedAt":"2025-09-01T10:00:00.000Z","startDate":"2025-09-01T10:00:00.000Z","endDate":null,"maxParticipants":null,"logo":"https://example.com/campaign-logo.jpg","video":null,"showInstructions":true,"showLeaderboard":true,"rateLimit":0,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"type":"SURVEY","contractId":null,"archivedAt":null}],"latestDraftCampaign":{"id":"cm3campaignid789","organizationId":"cly0d950o000310tjxcorg123","title":"Draft Campaign","status":"DRAFT","creatorId":"cm3creatorid456","createdAt":"2025-09-28T00:00:00.000Z","updatedAt":"2025-09-29T00:00:00.000Z","hero":{},"totalVotes":0,"pointStats":null,"participantsCount":0,"reward":null,"description":"Draft campaign description","publishedAt":null,"startDate":null,"endDate":null,"maxParticipants":null,"logo":null,"video":null,"showInstructions":true,"showLeaderboard":true,"rateLimit":0,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"type":"SURVEY","contractId":null,"archivedAt":null},"latestActiveCampaign":{"id":"cm3campaignid123","organizationId":"cly0d950o000310tjxcorg123","title":"Fan Survey Campaign","status":"PUBLISHED","creatorId":"cm3creatorid456","createdAt":"2025-09-01T00:00:00.000Z","updatedAt":"2025-09-15T00:00:00.000Z","hero":{},"totalVotes":350,"pointStats":null,"participantsCount":320,"reward":null,"description":"Share your feedback!","publishedAt":"2025-09-01T10:00:00.000Z","startDate":"2025-09-01T10:00:00.000Z","endDate":null,"maxParticipants":null,"logo":"https://example.com/campaign-logo.jpg","video":null,"showInstructions":true,"showLeaderboard":true,"rateLimit":0,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"type":"SURVEY","contractId":null,"archivedAt":null},"totalParticipantsForCreator":{"totalParticipants":1256,"last24HoursParticipantsGrowth":42}}}}}}}}}},"/creator/id/{creatorId}/group":{"post":{"summary":"Create creator group","description":"Create a new group for a Merchant with specified members","tags":["Merchant Groups"],"operationId":"create","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"groupName":{"description":"Name of the new group","example":"VIP Members","type":"string","minLength":1},"groupType":{"description":"Type of the group (e.g., FOLLOWER)","example":"FOLLOWER","type":"string","enum":["USER"]},"memberIds":{"description":"Array of user IDs to be included in the group","example":["clg0exampleuserid1","clg0exampleuserid2"],"minItems":1,"type":"array","items":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"}}},"required":["groupName","groupType","memberIds"]}}}},"responses":{"200":{"description":"Successfully created group","content":{"application/json":{"examples":{"success":{"summary":"Successful creation","value":{"data":{"id":"cm3newgroupid789","organizationId":"cly0d950o000310tjxcorg123","name":"VIP Members","type":"USER","creatorId":"cm3creatorid456","createdAt":"2025-09-30T12:00:00.000Z","updatedAt":"2025-09-30T12:00:00.000Z"}}}}}}}}}},"/creator/id/{creatorId}/products":{"get":{"summary":"List creator products","description":"Retrieve a list of products for a specific Merchant with optional status and search filtering","tags":["Merchant Products"],"operationId":"list","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"query","name":"status","schema":{"description":"Filter products by status","example":"PUBLISHED","anyOf":[{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"]},{"type":"array","items":{"type":"string","enum":["DRAFT","PUBLISHED","ARCHIVED"]}}]},"description":"Filter products by status"},{"in":"query","name":"search","schema":{"description":"Search products by name","example":"product name","type":"string"},"description":"Search products by name"}],"responses":{"200":{"description":"Successfully retrieved list of Merchant products","content":{"application/json":{"examples":{"success":{"summary":"Products list","value":{"data":[{"id":"cm3productid123","organizationId":"cly0d950o000310tjxcorg123","name":"Product Name","slug":"product-name","description":"Product description","type":"PHYSICAL","price":2999,"supply":100,"maxDiscount":500,"pointEligibility":"ANY","status":"PUBLISHED","logo":"https://example.com/product.jpg","subcategoryId":5,"allowedPointSources":[],"shippingType":"FLAT_RATE","shopifyProductId":null,"archivedAt":null,"merchantId":"cm3creatorid123","createdAt":"2025-09-01T00:00:00.000Z","updatedAt":"2025-09-15T00:00:00.000Z","salesCount":42}],"total":1}}}}}}}}},"/creator/id/{creatorId}/products/analytics":{"get":{"summary":"Get creator product analytics","description":"Retrieve detailed analytics and metrics for a creator's products over a specified timeframe","tags":["Merchant Products"],"operationId":"listAnalytics","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"query","name":"timeframe","schema":{"type":"string","enum":["week","month","month3","year","all"]},"required":true}],"responses":{"200":{"description":"Successfully retrieved product analytics data","content":{"application/json":{"examples":{"success":{"summary":"Analytics data","value":{"counts":[{"count":42,"orderDate":"2025-09-01T00:00:00.000Z"}],"totals":[{"total":125979,"orderDate":"2025-09-01T00:00:00.000Z"}]}}}}}}}}},"/creator/id/{creatorId}/products/sales":{"get":{"summary":"Get creator product sales","description":"Retrieve sales statistics for all products belonging to a specific Merchant","tags":["Merchant Products"],"operationId":"listSales","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Successfully retrieved product sales data","content":{"application/json":{"examples":{"success":{"summary":"Sales statistics","value":{"cm3productid123":42,"cm3productid456":17}}}}}}}}},"/creator/followers/{id}":{"get":{"summary":"List followers for a creator","description":"Returns paginated followers for the specified Merchant with optional search and sorting.","tags":["Merchant Followers"],"operationId":"get","parameters":[{"in":"path","name":"id","schema":{"description":"Merchant identifier to list followers for","example":"clg0examplecreatorid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Merchant identifier to list followers for"},{"in":"query","name":"page","schema":{"description":"Zero-indexed page number","example":0,"type":"integer","minimum":0,"maximum":9007199254740991},"description":"Zero-indexed page number"},{"in":"query","name":"limit","schema":{"description":"Page size for follower results","example":25,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"Page size for follower results"},{"in":"query","name":"query","schema":{"description":"Text search filter applied to follower names","example":"alex","type":"string","minLength":1},"description":"Text search filter applied to follower names"},{"in":"query","name":"sortDirection","schema":{"description":"Sort order for follower list","example":"asc","type":"string","enum":["asc","desc"]},"description":"Sort order for follower list"}],"responses":{"200":{"description":"Followers fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":{"data":[{"id":"cm3user1","organizationId":"cly0d950o000310tjxcorg123","username":"alex_smith","displayName":null,"email":"alex@example.com","emailVerified":true,"avatarUrl":"https://example.com/avatar.jpg","bio":"User bio","city":"San Francisco","state":"CA","createdAt":"2025-01-10T08:00:00.000Z","updatedAt":"2025-09-01T12:00:00.000Z","streamChatToken":null,"roles":[]}],"total":42,"page":0,"limit":25}}}}}}}}},"/creator/followers/{id}/top":{"get":{"summary":"Get top followers","description":"Returns the top-ranked followers for the specified Merchant.","tags":["Merchant Followers"],"operationId":"getTop","parameters":[{"in":"path","name":"id","schema":{"description":"Merchant identifier to fetch top-ranked followers for","example":"clg0examplecreatorid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Merchant identifier to fetch top-ranked followers for"}],"responses":{"200":{"description":"Top followers fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":[{"id":"cm3user1","username":"top_fan_1","avatarUrl":"https://example.com/avatar1.jpg","score":950,"totalMoments":45,"nftRedemptions":12,"nftCount":8,"totalPoints":5000},{"id":"cm3user2","username":"top_fan_2","avatarUrl":"https://example.com/avatar2.jpg","score":920,"totalMoments":42,"nftRedemptions":10,"nftCount":7,"totalPoints":4500}]}}}}}}}},"/creator/followers/{id}/growth":{"get":{"summary":"Get follower growth analytics","description":"Returns aggregated follower growth metrics for the specified Merchant over the selected time range.","tags":["Merchant Followers"],"operationId":"getGrowth","parameters":[{"in":"path","name":"id","schema":{"description":"Merchant identifier to fetch follower growth for","example":"clg0examplecreatorid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Merchant identifier to fetch follower growth for"},{"in":"query","name":"timeRange","schema":{"description":"Time window for growth analytics: 1W, 1M, 3M, 1Y, ALL","example":"1M","type":"string","enum":["1W","1M","3M","1Y","ALL"]},"required":true,"description":"Time window for growth analytics: 1W, 1M, 3M, 1Y, ALL"}],"responses":{"200":{"description":"Follower growth analytics fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":[{"date":"2025-09-01T00:00:00.000Z","totalFollowers":1208},{"date":"2025-09-02T00:00:00.000Z","totalFollowers":1250}]}}}}}}}},"/creator/{slug}/stats":{"get":{"summary":"Get creator statistics","description":"Returns aggregate Merchant statistics for the specified slug.","tags":["Merchant"],"operationId":"getStats","parameters":[{"in":"path","name":"slug","schema":{"description":"Kebab-case slug comprised of lowercase letters and numbers","example":"podium-campaign","type":"string","minLength":1},"required":true,"description":"Kebab-case slug comprised of lowercase letters and numbers"}],"responses":{"200":{"description":"Merchant statistics fetched successfully"}}}},"/creator/{slug}":{"get":{"summary":"Get creator by slug","description":"Returns Merchant profile data and whether the requesting viewer follows them.","tags":["Merchant"],"operationId":"getBySlug","parameters":[{"in":"path","name":"slug","schema":{"description":"Merchant slug used to locate the profile","example":"creator-handle","type":"string","minLength":1},"required":true,"description":"Merchant slug used to locate the profile"},{"in":"query","name":"profileViewerId","schema":{"description":"Authenticated viewer identifier to check follow relationship","example":"clg0exampleviewerid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"}}],"responses":{"200":{"description":"Merchant fetched successfully"}}}},"/creator/{slug}/collectibles/metadata":{"get":{"summary":"List creator collectibles metadata","description":"Returns NFTs associated with the specified Merchant slug.","tags":["Merchant Collectibles"],"operationId":"listMetadata","parameters":[{"in":"path","name":"slug","schema":{"description":"Merchant slug to retrieve collectibles metadata for","example":"creator-handle","type":"string","minLength":1},"required":true,"description":"Merchant slug to retrieve collectibles metadata for"}],"responses":{"200":{"description":"Collectibles metadata fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Collectibles list","value":{"data":[{"id":1,"organizationId":"cly0d950o000310tjxcorg123","nftContractId":42,"imageUrl":"https://example.com/nft.jpg","description":"Exclusive Merchant NFT","attributes":{},"externalUrl":"https://example.com/nft/1","animationUrl":null,"contract":{"id":42,"organizationId":"cly0d950o000310tjxcorg123","name":"Creator NFT Collection","symbol":"CNFT","points":100,"createdAt":"2025-09-01T00:00:00.000Z","chainId":8453,"proxyAddress":"0x1234567890abcdef","implementationAddress":"0xabcdef1234567890","metadataIpfsHash":"QmXYZ123...","updatedAt":"2025-09-15T00:00:00.000Z","maxSupply":1000,"transferable":true,"abiId":1,"abi":{"id":1,"name":"ERC721","json":{},"created_at":"2025-01-01T00:00:00.000Z"}}}]}}}}}}}}},"/creator/{slug}/rewards":{"get":{"summary":"List creator NFT rewards","description":"Returns NFT rewards associated with the specified Merchant slug.","tags":["Merchant Rewards"],"operationId":"list","parameters":[{"in":"path","name":"slug","schema":{"description":"Kebab-case slug comprised of lowercase letters and numbers","example":"podium-campaign","type":"string","minLength":1},"required":true,"description":"Kebab-case slug comprised of lowercase letters and numbers"}],"responses":{"200":{"description":"Merchant rewards fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Rewards list","value":[{"id":"cm3nftrewardid123","organizationId":"cly0d950o000310tjxcorg123","status":"PUBLISHED","contractId":null,"creatorId":"cm3creatorid456","airdropId":null,"createdAt":"2025-09-01T00:00:00.000Z","publishedAt":"2025-09-15T00:00:00.000Z","type":"POINTS","source":"EARNED","contract":null}]}}}}}}}},"/creator/{slug}/product/{productSlug}":{"get":{"summary":"Get creator product by slug","description":"Returns a specific product for the Merchant identified by the provided slugs.","tags":["Merchant Products"],"operationId":"getByProductSlug","parameters":[{"in":"path","name":"slug","schema":{"description":"Merchant slug identifying the catalog owner","example":"creator-handle","type":"string","minLength":1},"required":true,"description":"Merchant slug identifying the catalog owner"},{"in":"path","name":"productSlug","schema":{"description":"Product slug to locate within the Merchant catalog","example":"product-name","type":"string","minLength":1},"required":true,"description":"Product slug to locate within the Merchant catalog"},{"in":"query","name":"userId","schema":{"description":"Optional user ID for personalized results","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for personalized results"}],"responses":{"200":{"description":"Merchant product fetched successfully"}}}},"/creator/{slug}/products":{"get":{"summary":"List published creator products by slug","description":"Returns the creator's published products by creator slug, including pagination metadata.","tags":["Merchant Products"],"operationId":"listBySlug","parameters":[{"in":"path","name":"slug","schema":{"description":"Kebab-case slug comprised of lowercase letters and numbers","example":"podium-campaign","type":"string","minLength":1},"required":true,"description":"Kebab-case slug comprised of lowercase letters and numbers"},{"in":"query","name":"sort","schema":{"description":"Field name used for ordering results","example":"createdAt","default":"createdAt","type":"string"},"description":"Field name used for ordering results"},{"in":"query","name":"order","schema":{"description":"Sort direction when ordering results","example":"desc","default":"desc","type":"string","enum":["asc","desc"]},"description":"Sort direction when ordering results"},{"in":"query","name":"page","schema":{"description":"1-indexed page number","example":1,"default":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"1-indexed page number"},{"in":"query","name":"limit","schema":{"description":"Maximum number of records to return per page","example":25,"default":10,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"Maximum number of records to return per page"},{"in":"query","name":"userId","schema":{"description":"Optional user ID for personalized results","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for personalized results"}],"responses":{"200":{"description":"Merchant products fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Products list","value":{"data":[{"id":"cm3productid123","organizationId":"cly0d950o000310tjxcorg123","name":"Product Name","slug":"product-name","description":"Product description","type":"PHYSICAL","price":2999,"supply":100,"maxDiscount":500,"pointEligibility":"ANY","status":"PUBLISHED","logo":"https://example.com/product.jpg","subcategoryId":5,"allowedPointSources":[],"shippingType":"FLAT_RATE","shopifyProductId":null,"archivedAt":null,"merchantId":"cm3creatorid123","createdAt":"2025-09-01T00:00:00.000Z","updatedAt":"2025-09-15T00:00:00.000Z"}],"total":1}}}}}}}}},"/token-presales":{"get":{"summary":"Get token presales with optional Merchant/status filtering and pagination","description":"Returns a paginated list of token presales with optional filtering by Merchant ID and presale status.","tags":["Token Presales"],"operationId":"list","parameters":[{"in":"query","name":"creatorId","schema":{"description":"Optional Merchant ID to filter presales by","example":"clg0examplecreatorid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional Merchant ID to filter presales by"},{"in":"query","name":"status","schema":{"description":"Optional status or array of statuses to filter by (excludes draft)","example":["active","queued"],"anyOf":[{"type":"string","enum":["queued","pending","active","completed","ended"]},{"minItems":1,"type":"array","items":{"type":"string","enum":["queued","pending","active","completed","ended"]}}]},"description":"Optional status or array of statuses to filter by (excludes draft)"},{"in":"query","name":"page","schema":{"description":"Page number for pagination","example":1,"default":1,"type":"number","exclusiveMinimum":0},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"description":"Number of results per page","example":20,"default":10,"type":"number","exclusiveMinimum":0},"description":"Number of results per page"}],"responses":{"200":{"description":"Token presales fetched successfully"}}}},"/token-presales/{id}":{"get":{"summary":"Get up-to-date token presale details by its Podium ID","description":"Returns detailed information about a specific token presale including status, pricing, and availability.","tags":["Token Presales"],"operationId":"get","parameters":[{"in":"path","name":"id","schema":{"description":"Token presale identifier","example":"clg0examplepresaleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Token presale identifier"}],"responses":{"200":{"description":"Token presale details fetched successfully"}}}},"/token-presales/{id}/buy":{"post":{"summary":"Purchase a token presale allocation on behalf of a Metal user","description":"Creates a presale purchase transaction through Metal for a specified holder with a given USDC amount.","tags":["Token Presales"],"operationId":"buy","parameters":[{"in":"path","name":"id","schema":{"description":"Token presale identifier","example":"clg0examplepresaleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Token presale identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"holderId":{"description":"Metal holder ID for the user purchasing the presale","example":"holder_abc123xyz","type":"string","minLength":1},"usdcAmount":{"description":"Amount of USDC to spend on the presale purchase","example":100.5,"type":"number","exclusiveMinimum":0}},"required":["holderId","usdcAmount"]}}}},"responses":{"200":{"description":"Presale purchase completed successfully"}}}},"/discover":{"get":{"summary":"Get discover data with optional personalization","description":"Returns a curated mix of popular campaigns, Merchants, and collectibles. When authenticated and suggested=true, results are personalized based on user interests.","tags":["Discover"],"operationId":"list","parameters":[{"in":"query","name":"userId","schema":{"description":"Optional user ID for personalized results","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for personalized results"},{"in":"query","name":"suggested","schema":{"description":"Whether to personalize results based on user interests (requires authentication)","example":"true","type":"string"},"required":true,"description":"Whether to personalize results based on user interests (requires authentication)"},{"in":"query","name":"page","schema":{"description":"Page number for pagination","example":1,"default":1,"type":"number","minimum":0},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"description":"Number of results per page","example":20,"default":10,"type":"number","minimum":0},"description":"Number of results per page"}],"responses":{"200":{"description":"Discover data fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful discover data retrieval","value":{"data":{"campaigns":[],"creators":[],"collectibles":[]},"total":0,"page":1,"limit":10}}}}}}}}},"/discover/creators":{"get":{"summary":"Discover popular creators with optional personalization","description":"Returns a paginated list of popular Merchants on the platform. When authenticated and suggested=true, results are personalized based on user interests.","tags":["Discover"],"operationId":"listCreators","parameters":[{"in":"query","name":"userId","schema":{"description":"Optional user ID for personalized results","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for personalized results"},{"in":"query","name":"suggested","schema":{"description":"Whether to personalize results based on user interests (requires authentication)","example":"true","type":"string"},"required":true,"description":"Whether to personalize results based on user interests (requires authentication)"},{"in":"query","name":"page","schema":{"description":"Page number for pagination","example":1,"default":1,"type":"number","minimum":0},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"description":"Number of results per page","example":20,"default":10,"type":"number","minimum":0},"description":"Number of results per page"}],"responses":{"200":{"description":"Popular Merchants fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful creators retrieval","value":{"data":[{"id":"cm3creatorid456","organizationId":"cly0d950o000310tjxcorg123","displayName":"Example Creator","avatarUrl":"https://example.com/avatar.jpg","description":"Merchant bio
","heroUrl":"https://example.com/hero.jpg","slug":"example-creator","createdAt":"2025-01-15T10:00:00.000Z","updatedAt":"2025-09-30T14:00:00.000Z","streamChatToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example","flatShippingRate":500,"pointsAccepted":"ANY","roles":["PUBLISHER"],"stripeOnboardingReminderSentAt":null,"stripeOnboardingReminderClaimedUntil":null,"followersCount":1250,"productSoldQuantity":450,"product":{"id":1,"name":"Example Product","slug":"example-product","price":100,"medialUrl":"https://example.com/product.jpg"}}],"total":200,"page":1,"limit":10}}}}}}}}},"/discover/collectibles":{"get":{"summary":"Discover popular NFT collectibles with optional personalization","description":"Returns a paginated list of popular NFT contracts and collectibles. When authenticated and suggested=true, results are personalized based on user interests.","tags":["Discover"],"operationId":"listCollectibles","parameters":[{"in":"query","name":"userId","schema":{"description":"Optional user ID for personalized results","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for personalized results"},{"in":"query","name":"suggested","schema":{"description":"Whether to personalize results based on user interests (requires authentication)","example":"true","type":"string"},"required":true,"description":"Whether to personalize results based on user interests (requires authentication)"},{"in":"query","name":"page","schema":{"description":"Page number for pagination","example":1,"default":1,"type":"number","minimum":0},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"description":"Number of results per page","example":20,"default":10,"type":"number","minimum":0},"description":"Number of results per page"}],"responses":{"200":{"description":"Popular collectibles fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful collectibles retrieval","value":{"data":[{"id":42,"name":"Example NFT Collection","points":500,"chainId":84532,"proxyAddress":"0x1234567890abcdef1234567890abcdef12345678","uniqueOwnersCount":250,"creator":{"id":"cm3creatorid123","displayName":"Creator Name","avatarUrl":"https://example.com/creator-avatar.jpg","slug":"creator-name"},"metadata":{"imageUrl":"ipfs://QmExampleHash123/image.png","animationUrl":"ipfs://QmExampleHash123/video.mp4"}}],"total":150,"page":1,"limit":10}}}}}}}}},"/discover/campaigns":{"get":{"summary":"Discover popular campaigns with optional personalization","description":"Returns a paginated list of popular campaigns. When authenticated and suggested=true, results are personalized based on user interests and may include featured campaigns.","tags":["Discover"],"operationId":"listCampaigns","parameters":[{"in":"query","name":"userId","schema":{"description":"Optional user ID for personalized results","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for personalized results"},{"in":"query","name":"suggested","schema":{"description":"Whether to personalize results based on user interests (requires authentication)","example":"true","type":"string"},"required":true,"description":"Whether to personalize results based on user interests (requires authentication)"},{"in":"query","name":"page","schema":{"description":"Page number for pagination","example":1,"default":1,"type":"number","minimum":0},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"description":"Number of results per page","example":20,"default":10,"type":"number","minimum":0},"description":"Number of results per page"}],"responses":{"200":{"description":"Popular campaigns fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful campaigns retrieval","value":{"data":[{"id":"cm0bjzgo30004hz1iwbc75dpi","title":"Vote for Your Favorite Style","description":"Help us choose the best designs for our next collection. Cast your vote and earn rewards!","hero":[{"alt":"Campaign hero image","url":"https://example.com/campaign-hero.jpg"}],"endDate":null,"type":"SWIPE","votesCount":350,"reward":{"points":"100"},"creator":{"id":"clxueqqth000084u356vmxeik","displayName":"Example Creator","avatarUrl":"https://example.com/avatar.jpg","slug":"example-creator"}}],"total":125,"page":1,"limit":10}}}}}}}}},"/featured/creators":{"get":{"summary":"Get featured creators by slugs","description":"Returns a list of Merchants in the order specified by the provided comma-separated creator slugs. Used for displaying curated featured Merchant collections.","tags":["Featured Content"],"operationId":"listCreators","parameters":[{"in":"query","name":"q","schema":{"description":"Comma-separated list of Merchant slugs to retrieve in specified order","example":"creator-one,creator-two,creator-three","type":"string","minLength":1},"required":true,"description":"Comma-separated list of Merchant slugs to retrieve in specified order"}],"responses":{"200":{"description":"Featured Merchants fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":[{"id":"cm1creator456","avatarUrl":"https://storage.googleapis.com/bucket/Merchant-avatar.jpg","description":"Digital artist creating unique NFT collections and experiences","displayName":"Cool Creator","heroUrl":"https://storage.googleapis.com/bucket/Merchant-hero.jpg","slug":"cool-creator","followersCount":1245},{"id":"cm2creator789","avatarUrl":"https://storage.googleapis.com/bucket/artist-avatar.jpg","description":"Music producer and community builder connecting fans through exclusive content","displayName":"Artist Name","heroUrl":"https://storage.googleapis.com/bucket/artist-hero.jpg","slug":"artist-name","followersCount":3567}]}}}}}}}},"/featured/campaigns":{"get":{"summary":"Get featured campaigns by IDs","description":"Returns a list of campaigns in the order specified by the provided comma-separated campaign IDs. Used for displaying curated featured campaign collections.","tags":["Featured Content"],"operationId":"listCampaigns","parameters":[{"in":"query","name":"q","schema":{"description":"Comma-separated list of campaign IDs to retrieve in specified order","example":"clg0examplecampaignid1,clg0examplecampaignid2","type":"string","minLength":1},"required":true,"description":"Comma-separated list of campaign IDs to retrieve in specified order"}],"responses":{"200":{"description":"Featured campaigns fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":[{"id":"cm3campaign1xyz","title":"Share Your Story","description":"Tell us about your journey and get featured on our platform","endDate":"2025-10-15T23:59:59.000Z","hero":"https://storage.googleapis.com/bucket/campaign-hero.jpg","type":"USER_GENERATED_CONTENT","creator":{"id":"cm1creator456","avatarUrl":"https://storage.googleapis.com/bucket/Merchant-avatar.jpg","displayName":"Cool Creator","slug":"cool-creator"},"participants":142},{"id":"cm3campaign2abc","title":"Vote for Your Favorite","description":"Help us decide what to create next by voting for your top choice","endDate":"2025-10-31T23:59:59.000Z","hero":"https://storage.googleapis.com/bucket/vote-hero.jpg","type":"VOTE","creator":{"id":"cm2creator789","avatarUrl":"https://storage.googleapis.com/bucket/another-avatar.jpg","displayName":"Artist Name","slug":"artist-name"},"participants":89}]}}}}}}}},"/featured/products":{"get":{"summary":"Get featured products by IDs","description":"Returns a list of products with media and saved status in the order specified by the provided comma-separated product IDs. Used for displaying curated featured product collections.","tags":["Featured Content"],"operationId":"listProducts","parameters":[{"in":"query","name":"userId","schema":{"description":"Optional user ID for personalized results","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for personalized results"},{"in":"query","name":"q","schema":{"description":"Comma-separated list of product IDs to retrieve in specified order","example":"clg0exampleproductid1,clg0exampleproductid2","type":"string","minLength":1},"required":true,"description":"Comma-separated list of product IDs to retrieve in specified order"}],"responses":{"200":{"description":"Featured products fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":[{"id":"cm3prod123xyz","name":"Limited Edition T-Shirt","slug":"limited-edition-t-shirt","price":2999,"description":"Exclusive merch from your favorite Merchant","logo":"https://storage.googleapis.com/bucket/product-logo.jpg","media":[{"productId":"cm3prod123xyz","type":"IMAGE","url":"https://storage.googleapis.com/bucket/product-image1.jpg","order":1,"createdAt":"2025-09-15T10:00:00Z"},{"productId":"cm3prod123xyz","type":"IMAGE","url":"https://storage.googleapis.com/bucket/product-image2.jpg","order":2,"createdAt":"2025-09-15T10:01:00Z"}],"creator":{"id":"cm1creator456","avatarUrl":"https://storage.googleapis.com/bucket/avatar.jpg","displayName":"Cool Creator","slug":"cool-creator","followersCount":1245},"saved":false},{"id":"cm3prod789abc","name":"Digital Art Print","slug":"digital-art-print","price":999,"description":"High-resolution digital artwork","logo":"https://storage.googleapis.com/bucket/digital-logo.jpg","media":[{"productId":"cm3prod789abc","type":"IMAGE","url":"https://storage.googleapis.com/bucket/digital-art.jpg","order":1,"createdAt":"2025-09-20T14:00:00Z"}],"creator":{"id":"cm2artist789","avatarUrl":"https://storage.googleapis.com/bucket/artist-avatar.jpg","displayName":"Digital Artist","slug":"digital-artist","followersCount":3567},"saved":true}]}}}}}}}},"/admin/app-config":{"get":{"summary":"Resolve app config for current org","description":"Returns the resolved app config for the authenticated organization using the x-app-id header.","tags":["Admin"],"operationId":"listAppConfig","responses":{"200":{"description":"Resolved app config response","content":{"application/json":{"examples":{"success":{"summary":"App config resolved","value":{"organizationId":"cmjaakyet0009od0zvzq2ompa","appId":"reid-brendon-demo","appConfig":{"id":"cml15uubk0001dvynkw69alo1","organizationId":"cmjaakyet0009od0zvzq2ompa","appId":"reid-brendon-demo","primaryNetwork":"ARC_TESTNET","rewardMode":"USDC","enabledNetworks":["BASE","ARC_TESTNET"],"visibleCapabilities":["commerce","agentic"],"createdAt":"2026-01-30T17:32:22.400Z","updatedAt":"2026-01-30T17:32:22.400Z"}}}}}}}}}},"/admin/tasks":{"get":{"summary":"List tasks flagged for manual review","description":"Returns tasks where the oracle evaluation had low confidence and flagged for admin review.","tags":["Admin"],"operationId":"getTasksPendingReview","responses":{"200":{"description":"Pending review tasks fetched"}}},"post":{"summary":"Manually approve or reject a flagged task","description":"Admin resolves a task that was flagged for manual review. Generates HMAC and triggers on-chain settlement.","tags":["Admin"],"operationId":"resolveTaskManually","responses":{"200":{"description":"Task resolved"}}}},"/admin/campaigns":{"get":{"summary":"List campaigns by status","description":"Returns campaigns filtered by status with pagination support for admin reviewers.","tags":["Admin"],"operationId":"listCampaigns","parameters":[{"in":"query","name":"status","schema":{"description":"Status of the campaigns to filter by","example":"PUBLISHED","type":"string","enum":["DRAFT","SUBMITTED","APPROVED","DENIED","PUBLISHED","ENDED","PAUSED","ARCHIVED"]},"description":"Status of the campaigns to filter by"},{"in":"query","name":"page","schema":{"description":"Page number to fetch","example":1,"type":"number","minimum":0},"description":"Page number to fetch"},{"in":"query","name":"limit","schema":{"description":"Number of campaigns to fetch per page","example":20,"type":"number","minimum":0},"description":"Number of campaigns to fetch per page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"campaigns":{"type":"object","properties":{"total":{"description":"Total number of campaigns matching the filter","example":42,"type":"number"},"results":{"description":"Campaigns matching the current filter","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"updatedAt":{"type":"string"},"status":{"type":"string","enum":["DRAFT","SUBMITTED","APPROVED","DENIED","PUBLISHED","ENDED","PAUSED","ARCHIVED"]},"creator":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"}},"required":["id","displayName"],"additionalProperties":false}},"required":["id","updatedAt","status","creator"],"additionalProperties":false}}},"required":["total","results"],"additionalProperties":false}},"required":["campaigns"],"additionalProperties":false},"examples":{"success":{"summary":"Successful campaign list retrieval","value":{"campaigns":{"total":42,"results":[{"id":"cm3campaign123","status":"PUBLISHED","updatedAt":"2025-09-20T18:22:37.000Z","creator":{"id":"cm3creator456","displayName":"Kiki World"}}]}}}}}}}}}},"/admin/campaigns/{id}/status":{"patch":{"summary":"Update campaign status (admin only)","description":"Approves or denies a campaign. Requires CAMPAIGN_ADMIN role.","tags":["Admin Campaigns Status"],"operationId":"update","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"description":"User ID performing the campaign review","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"status":{"description":"New campaign review status","example":"APPROVED","type":"string","enum":["APPROVED","DENIED"]}},"required":["userId","status"]}}}},"responses":{"200":{"description":"Status updated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"description":"Whether the operation succeeded","example":true,"type":"boolean"}},"required":["ok"],"additionalProperties":false},"examples":{"success":{"summary":"Successful status update","value":{"ok":true}}}}}}}}},"/merchants":{"post":{"summary":"Create a brand-merchant from scratch","description":"Mints a fresh BRAND or INDIVIDUAL merchant in the caller's org without going through the legacy Creator subtype, and issues a domain-verification challenge. Returns the new Merchant with `verifiedAt: null`; call POST /merchants/{merchantId}/verify-domain to complete the claim.\n\nUse POST /merchants/claim instead when an existing `BrandProfile` already covers the apex (the brand-discovery pipeline has enriched it). Returns 409 if the apex is already claimed in the caller's org.","tags":["Merchant"],"operationId":"createBrandMerchant","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchantType":{"description":"Subtype of the new merchant. CREATOR is reserved for the legacy /creator/* surface and is not creatable here.","example":"BRAND","type":"string","enum":["BRAND","INDIVIDUAL"]},"displayName":{"description":"Public display name (e.g. \"Glossier\")","example":"Glossier","type":"string","minLength":1,"maxLength":191},"slug":{"description":"URL-safe slug","example":"glossier","type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$"},"description":{"description":"Plain-text storefront description","example":"Cult-favorite skincare and beauty.","type":"string","maxLength":2000},"avatarUrl":{"type":"string","format":"uri"},"heroUrl":{"type":"string","format":"uri"},"brandDomainApex":{"description":"The brand domain. Anything resolvable to an eTLD+1 — `glossier.com`, `https://www.glossier.com/products`, `shop.glossier.com` — all canonicalize server-side.","example":"glossier.com","type":"string","minLength":3,"pattern":"^(?:https?:\\/\\/)?(?:[a-z0-9-]+\\.)+[a-z]{2,}(?::\\d+)?(?:\\/.*)?$"},"verificationMethod":{"description":"Domain-verification path. `dns_txt` instructs the operator to publish a TXT record at `_podium-verify.Limited edition merch from the Aurora tour.
","type":"string"},"media":{"type":"object","properties":{"nodes":{"default":[],"type":"array","items":{"type":"object","properties":{"id":{"description":"Media node ID","example":"gid://shopify/ProductImage/987654321","type":"string"},"image":{"type":"object","properties":{"url":{"description":"URL pointing to the media asset","example":"https://cdn.shopify.com/product-image.jpg","type":"string","format":"uri"}},"required":["url"]},"alt":{"description":"Optional alt text for the media asset","example":"Campaign merchandise hero shot","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","alt"]}}},"additionalProperties":false},"variants":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Variant node ID","example":"gid://shopify/ProductVariant/123456789","type":"string"},"title":{"description":"Variant title","example":"Gold / Large","type":"string"},"price":{"description":"Variant price as a string","example":"150.00","type":"string"},"sku":{"description":"Variant SKU if assigned","example":"AURORA-JKT-G-L","anyOf":[{"type":"string"},{"type":"null"}]},"inventoryQuantity":{"description":"Current inventory level for the variant","example":42,"type":"number"},"compareAtPrice":{"description":"Original price when on sale","example":"175.00","anyOf":[{"type":"string"},{"type":"null"}]},"selectedOptions":{"type":"array","items":{"type":"object","properties":{"name":{"description":"Option name (e.g., Color, Size)","example":"Color","type":"string"},"value":{"description":"Selected option value","example":"Gold","type":"string"}},"required":["name","value"]}}},"required":["id","title","price","sku","inventoryQuantity"]}}},"required":["nodes"]},"options":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Product option identifier","example":"gid://shopify/ProductOption/456789123","type":"string"},"name":{"description":"Option name","example":"Size","type":"string"},"position":{"description":"Display order for the option","example":1,"type":"number"},"values":{"description":"Possible values for the option","example":["Small","Medium","Large"],"type":"array","items":{"type":"string"}}},"required":["id","name","position","values"]}}},"required":["id","title","handle","status","descriptionHtml","media","variants","options"]}}},"required":["productNodes"]}},"required":["type","data"]}}}},"responses":{"200":{"description":"Sync initiated successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful sync initiation","value":{"ok":true}}}}}}}}},"/shopify/shop/{creatorId}":{"get":{"summary":"Get Shopify domain for creator","description":"Returns the connected Shopify store domain for a Merchant. Requires authentication.","tags":["Shopify"],"operationId":"getShopByCreatorId","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Shopify domain fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful domain retrieval","value":{"shopifyDomain":"example-store.myshopify.com"}}}}}}}}},"/shopify/shop/{creatorId}/{shopifyDomain}":{"delete":{"summary":"Delete Shopify store for creator","description":"Disconnects a Shopify store from a Merchant. Unregisters webhooks and removes the store association. Requires authentication.","tags":["Shopify"],"operationId":"deleteShopByShopifyDomain","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"path","name":"shopifyDomain","schema":{"description":"Shopify store domain to disconnect","example":"example-shop.myshopify.com","type":"string","minLength":5,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*\\.myshopify\\.com$"},"required":true,"description":"Shopify store domain to disconnect"}],"responses":{"200":{"description":"Shopify store disconnected successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful store disconnection","value":{"success":true}}}}}}}}},"/shopify/products/available/{creatorId}":{"get":{"summary":"List available Shopify products for creator","description":"Returns a list of all Shopify products available for a Merchant from their connected Shopify store. Requires authentication.","tags":["Shopify"],"operationId":"getProductsAvailableByCreatorId","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Shopify products fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful products retrieval","value":{"products":[]}}}}}}}}},"/shopify/install/{creatorId}":{"get":{"summary":"Initialize Shopify app installation for creator","description":"Starts the Shopify OAuth flow for a Merchant. Validates the shop domain, creates a state token, and redirects to Shopify authorization URL.","tags":["Shopify"],"operationId":"install","parameters":[{"in":"path","name":"creatorId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"query","name":"shop","schema":{"description":"Shopify store domain in myshopify.com format","example":"creator-shop.myshopify.com","type":"string","minLength":5,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*\\.myshopify\\.com$"},"required":true,"description":"Shopify store domain in myshopify.com format"}],"responses":{"200":{"description":"OK"},"302":{"description":"Redirects to Shopify authorization URL"}}}},"/x402/order/{id}/pay":{"post":{"summary":"Pay for order via x402","description":"\nPay for an order using the x402 payment protocol.\n\n**Flow:**\n1. Call this endpoint without `X-PAYMENT` header to get payment requirements (402 response)\n2. Create a payment using the requirements (via x402-compatible wallet)\n3. Call this endpoint again with `X-PAYMENT` header containing the payment\n4. On success, order status is updated to PAID\n\n**Requirements:**\n- Organization must have x402 enabled (`x402Enabled: true` in OrgSettings)\n- Organization must have a valid `x402PayToAddress` configured\n- Order must exist and be in OPEN or PAYMENT_PENDING status\n\n**Payment:**\n- Price is calculated from order items (subtotal + shipping)\n- Payment goes directly to the organization's configured wallet\n- USDC on the configured network (default: base-sepolia)\n","tags":["x402","Orders"],"operationId":"createOrderPay","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Payment successful - order marked as paid","content":{"application/json":{"examples":{"success":{"summary":"Successful payment","value":{"success":true,"message":"Payment successful","orderId":"clxxxxxxxxxxxxxxxxxx","status":"PAID","payment":{"transactionHash":"0x1234567890abcdef...","network":"base-sepolia","amount":"1000000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}}}}}},"400":{"description":"Bad request - order not found or already paid","content":{"application/json":{"examples":{"notFound":{"summary":"Order not found","value":{"error":"Order not found"}},"alreadyPaid":{"summary":"Order already paid","value":{"error":"Order is already paid"}}}}}},"402":{"description":"Payment required - returns x402 payment requirements","content":{"application/json":{"examples":{"paymentRequired":{"summary":"Payment requirements","value":{"x402Version":1,"error":"X-PAYMENT header is required","accepts":[{"scheme":"exact","network":"base-sepolia","maxAmountRequired":"10000000","resource":"https://api.example.com/api/v1/x402/orders/clxxx/pay","description":"Order payment","mimeType":"application/json","payTo":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb","maxTimeoutSeconds":300,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}]}}}}}},"403":{"description":"x402 not enabled for this organization","content":{"application/json":{"examples":{"disabled":{"summary":"x402 not enabled","value":{"error":"x402 payments are not enabled for this organization"}},"notConfigured":{"summary":"x402 not configured","value":{"error":"x402 payment address not configured for this organization"}}}}}}}}},"/guest/order":{"post":{"summary":"Create guest order with product","description":"Creates a new order for a guest user with the specified product. Requires guest authentication.","tags":["Guests"],"operationId":"createOrder","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"description":"Unique identifier of the product to order","example":"clg0exampleproductid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"variantIds":{"description":"Optional array of product variant IDs to include in the order","example":["clg0examplevariantid1","clg0examplevariantid2"],"type":"array","items":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"}},"quantity":{"description":"Quantity of the product to order","example":1,"default":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["productId"]}}}},"responses":{"200":{"description":"Guest order created successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful order creation","value":{"order":{"id":"cm3order456xyz","organizationId":"cly0d950o000310tjxcorg123","shippingFee":0,"taxFee":0,"points":0,"status":"OPEN","shippingStatus":"PENDING","shippingInfo":null,"buyerEmail":null,"buyerName":null,"buyerPhone":null,"appId":null,"idempotencyKey":null,"createdAt":"2025-09-30T10:00:00.000Z","updatedAt":"2025-09-30T10:00:00.000Z"}}}}}}}}}},"/guest/order/{id}":{"get":{"summary":"Get guest order details","description":"Returns detailed information about a specific guest order. Requires guest authentication.","tags":["Guests"],"operationId":"getOrder","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Guest order details fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":{"order":{"id":"cm3order456xyz","organizationId":"cly0d950o000310tjxcorg123","shippingFee":500,"taxFee":0,"points":0,"status":"OPEN","shippingStatus":"PENDING","shippingInfo":null,"buyerEmail":"guest@example.com","buyerName":null,"buyerPhone":null,"appId":null,"idempotencyKey":null,"createdAt":"2025-09-30T10:00:00.000Z","updatedAt":"2025-09-30T10:00:00.000Z","userOrder":null,"guestOrder":{"id":1,"organizationId":"cly0d950o000310tjxcorg123","guestId":1,"orderId":"cm3order456xyz","guest":{"id":1,"email":"guest@example.com"}},"paymentIntent":null,"userOrderTxs":[],"items":[{"id":1,"organizationId":"cly0d950o000310tjxcorg123","orderId":"cm3order456xyz","productId":"cm3prod123","quantity":2,"price":2999,"productName":"Cool T-Shirt","productSlug":"cool-t-shirt","selectedAttributes":null,"shippingStatus":"PENDING","createdAt":"2025-09-30T10:00:00.000Z","attributes":[],"product":{"id":"cm3prod123","organizationId":"cly0d950o000310tjxcorg123","name":"Cool T-Shirt","slug":"cool-t-shirt","description":"A really cool shirt","type":"PHYSICAL","price":2999,"supply":100,"maxDiscount":500,"pointEligibility":"ANY","status":"PUBLISHED","logo":"https://example.com/logo.jpg","subcategoryId":3,"allowedPointSources":[],"shopifyProductId":null,"archivedAt":null,"merchantId":"cm3creatorid123","createdAt":"2025-09-15T10:00:00.000Z","updatedAt":"2025-09-28T15:30:00.000Z","shippingType":"FLAT_RATE","media":[],"creatorProduct":null}}]}}}}}}}}}},"/guest/order/{id}/payment-failed":{"post":{"summary":"Mark guest order payment as failed","description":"Updates the status of a guest order to PAYMENT_FAILED. Requires guest authentication.","tags":["Guests"],"operationId":"createOrderPaymentFailed","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Order status updated successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful status update","value":{"ok":true}}}}}}}}},"/guest/order/{id}/item/{orderItemId}":{"delete":{"summary":"Remove a product from an order in the given quantity","description":"Removes the specified quantity of an order item from a guest order. If quantity is not provided, removes the entire item. Requires guest authentication.","tags":["Guests"],"operationId":"deleteOrderItemByOrderItemId","parameters":[{"in":"path","name":"id","schema":{"description":"Unique identifier of the guest order","example":"clg0exampleguestorderid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Unique identifier of the guest order"},{"in":"path","name":"orderItemId","schema":{"description":"Numeric identifier of the order item to remove","example":123,"type":"integer","minimum":0,"maximum":9007199254740991},"required":true,"description":"Numeric identifier of the order item to remove"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"description":"Quantity of the item to remove from the order","example":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}}}}},"responses":{"200":{"description":"Order item removed successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful removal","value":{"success":true}}}}}}}}},"/guest/order/{id}/checkout":{"post":{"summary":"Process guest order checkout","description":"Initiates the checkout process for a guest order, creating a Stripe payment intent and returning the client secret. Requires guest authentication.","tags":["Guests"],"operationId":"checkout","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Checkout initiated successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful checkout initiation","value":{"clientSecret":"pi_3Example1234567890_secret_Example1234567890"}}}}}}}}},"/guest/order/{id}/checkout/coinbase":{"patch":{"summary":"Process guest Coinbase checkout","description":"Processes a Coinbase Commerce checkout for a guest order. Requires guest authentication.","tags":["Guests"],"operationId":"updateOrderCheckoutCoinbase","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"callsId":{"description":"Coinbase Calls session identifier tying the payment to a checkout","example":"35d6d9c1-d7b0-4f1d-9a9f-6d957fa7a1ab","type":"string","minLength":1},"amount":{"description":"Total payment amount expected from Coinbase in USDC","example":125.75,"type":"number","exclusiveMinimum":0},"customer":{"type":"object","properties":{"email":{"description":"Verified email Coinbase associates with the payment customer","example":"fan@example.com","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"physicalAddress":{"type":"object","properties":{"address1":{"description":"Primary street line for shipping/billing purposes","example":"123 Market Street","type":"string","minLength":1},"address2":{"description":"Optional second address line if provided","example":"Unit 5B","type":"string"},"city":{"description":"City associated with the postal address","example":"San Francisco","type":"string","minLength":1},"state":{"description":"State or province associated with the postal address","example":"CA","type":"string","minLength":1},"postalCode":{"description":"Postal or ZIP code associated with the postal address","example":"94105","type":"string","minLength":1},"countryCode":{"description":"ISO 3166-1 alpha-2 country code","example":"US","type":"string","minLength":1},"name":{"type":"object","properties":{"firstName":{"description":"Customer first name as returned from Coinbase","example":"Taylor","type":"string","minLength":1},"familyName":{"description":"Customer last name as returned from Coinbase","example":"Swift","type":"string","minLength":1}},"required":["firstName","familyName"]}},"required":["address1","city","state","postalCode","countryCode","name"]}},"required":["email","physicalAddress"]}},"required":["callsId","amount","customer"]}}}},"responses":{"200":{"description":"Coinbase checkout processed successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful Coinbase checkout","value":{"coinbaseUser":{"id":1,"organizationId":"cly0d950o000310tjxcorg123","callsId":"cb_user_123abc","email":"guest@example.com","firstName":"John","lastName":"Doe","address1":"123 Main St","address2":null,"city":"San Francisco","state":"CA","postalCode":"94102","countryCode":"US","createdAt":"2025-09-30T10:00:00.000Z","updatedAt":"2025-09-30T10:00:00.000Z"},"coinbasePayment":{"id":1,"organizationId":"cly0d950o000310tjxcorg123","orderId":"cm3order456","callsId":"cb_123abc456def","amount":2999,"status":"PENDING","coinbaseUserId":1,"createdAt":"2025-09-30T10:00:00.000Z","updatedAt":"2025-09-30T10:00:00.000Z"},"order":{"id":"cm3order456","organizationId":"cly0d950o000310tjxcorg123","shippingFee":500,"taxFee":0,"points":0,"status":"PAID","shippingStatus":"PENDING","shippingInfo":null,"buyerEmail":"guest@example.com","buyerName":"Jane Doe","buyerPhone":null,"appId":null,"idempotencyKey":null,"createdAt":"2025-09-30T10:00:00.000Z","updatedAt":"2025-09-30T10:00:00.000Z"}}}}}}}}}},"/guest/order/{id}/product/{productId}":{"post":{"summary":"Add a product to an order in the given quantity","description":"Adds the specified product and quantity to a guest order, with optional variant selection. Requires guest authentication.","tags":["Guests"],"operationId":"createOrderProductByProductId","parameters":[{"in":"path","name":"id","schema":{"description":"Unique identifier of the guest order","example":"clg0exampleguestorderid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Unique identifier of the guest order"},{"in":"path","name":"productId","schema":{"description":"Unique identifier of the product to add","example":"clg0exampleproductid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Unique identifier of the product to add"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"description":"Quantity of the product to add to the order","example":3,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"variantIds":{"description":"Optional array of product variant IDs to include","example":["clg0examplevariantid1","clg0examplevariantid2"],"type":"array","items":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"}}}}}}},"responses":{"200":{"description":"Product added to order successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful product addition","value":{"userOrderItem":{"id":2,"orderId":"cm3order456xyz","productId":"cm3prod789","quantity":3,"unitPrice":1999,"createdAt":"2025-09-30T10:30:00.000Z"}}}}}}}}}},"/guest/{id}":{"patch":{"summary":"Update guest email","description":"Updates the email address for a guest user. Requires guest authentication.","tags":["Guest"],"operationId":"update","parameters":[{"in":"path","name":"id","schema":{"description":"Unique numeric identifier for the guest","example":123,"type":"number","exclusiveMinimum":0},"required":true,"description":"Unique numeric identifier for the guest"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"description":"New email address for the guest","example":"guest@example.com","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["email"]}}}},"responses":{"200":{"description":"Guest email updated successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful update","value":{"guest":{"id":123,"organizationId":"cly0d950o000310tjxcorg123","email":"guest@example.com","createdAt":"2025-09-15T10:00:00.000Z","updatedAt":"2025-09-30T14:30:00.000Z"}}}}}}}}}},"/product/{id}/buy-now":{"post":{"summary":"Buy product now","description":"Creates an order for immediate product purchase. Supports both authenticated and guest users. Optionally uses Stripe for payment.","tags":["Product"],"operationId":"buyNow","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"query","name":"userId","schema":{"description":"Optional user ID for authenticated purchase","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for authenticated purchase"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"description":"Number of product units to purchase","example":2,"type":"integer","minimum":1,"maximum":9007199254740991},"variantIds":{"description":"Array of variant IDs for the product","example":["clg0examplevariantid1","clg0examplevariantid2"],"default":[],"type":"array","items":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"}},"shouldUseStripe":{"description":"Whether to use Stripe for payment processing","example":true,"default":true,"type":"boolean"}},"required":["quantity"]}}}},"responses":{"200":{"description":"Order created successfully"}}}},"/tasks":{"get":{"summary":"List tasks for authenticated organization","description":"Returns paginated tasks, optionally filtered by status or campaign. Scoped to authenticated org via RLS.","tags":["Tasks"],"operationId":"listTasks","responses":{"200":{"description":"Tasks fetched successfully"}}},"post":{"summary":"Create a task with USDC escrow","description":"Provisions tenant pools if needed, creates task onchain via TaskPoolImplementation, and records in DB.","tags":["Tasks"],"operationId":"createTask","responses":{"200":{"description":"Task created successfully"}}}},"/tasks/pools":{"get":{"summary":"Get tenant task/reward pool info and balances","description":"Returns pool addresses, onchain USDC balances, and pending solver rewards. Provisions pools if first call.","tags":["Tasks"],"operationId":"getTenantPools","responses":{"200":{"description":"Pool info fetched"}}},"post":{"summary":"Provision TaskPool + RewardPool for authenticated org","description":"Idempotent. Deploys BeaconProxy pair via TaskPoolFactory.createTenantPools() if not already deployed.","tags":["Tasks"],"operationId":"provisionTenantPools","responses":{"200":{"description":"Pools provisioned or already exist"}}}},"/tasks/{taskId}":{"get":{"summary":"Get task by ID","tags":["Tasks"],"operationId":"getTask","responses":{"200":{"description":"Task fetched successfully"}}},"delete":{"summary":"Cancel an open or claimed task","description":"Cancels task onchain and refunds escrowed USDC to merchant balance.","tags":["Tasks"],"operationId":"cancelTask","responses":{"200":{"description":"Task cancelled successfully"}}}},"/tasks/{taskId}/verify":{"post":{"summary":"Oracle callback — resolve task verification","description":"Called by Podium oracle service after evaluating task submission. Verified via HMAC signature. On approval, triggers VerificationEngine.resolveVerification() onchain which calls TaskPool.settleTask().","tags":["Tasks"],"operationId":"resolveTaskVerification","responses":{"200":{"description":"Verification resolved successfully"},"401":{"description":"Invalid or expired HMAC signature"}}}},"/campaign":{"post":{"summary":"Create a new campaign","description":"Creates a new campaign for the authenticated Merchant.","tags":["Campaigns"],"operationId":"create","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"creatorId":{"description":"Merchant identifier launching the campaign","example":"clg0examplecreatorid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"type":{"description":"Campaign type to initialize","example":"SWIPE","type":"string","enum":["MULTIVARIANT","SWIPE","UGC","SURVEY"]}},"required":["creatorId","type"]}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Campaign created successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaign created","value":{"id":"cm3campaign123xyz","organizationId":"cly0d950o000310tjxcorg123","creatorId":"cm3creator456","type":"SWIPE","status":"DRAFT","title":null,"description":null,"startDate":null,"endDate":null,"maxParticipants":null,"hero":null,"video":null,"showInstructions":true,"showLeaderboard":true,"publishedAt":null,"contractId":null,"logo":null,"rateLimit":0,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"archivedAt":null,"createdAt":"2025-09-30T10:00:00.000Z","updatedAt":"2025-09-30T10:00:00.000Z"}}}}}}}}},"/campaign/{id}":{"get":{"summary":"Get campaign by ID","description":"Returns campaign details including reward stats when applicable.","tags":["Campaigns"],"operationId":"get","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"query","name":"userId","schema":{"description":"Optional user ID for personalized results","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for personalized results"}],"responses":{"200":{"description":"Campaign retrieved successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaign with details","value":{"id":"clyiy21mg0001b2nlbhmr01zx","organizationId":"cly0d950o000310tjxcorg123","status":"PUBLISHED","type":"MULTIVARIANT","title":"Bug Test","description":"is it a bug?","startDate":null,"endDate":null,"maxParticipants":1000,"hero":[{"alt":"Campaign Hero Image","url":"https://cdn.example.com/campaigns/clyiy21mg0001/hero.png"}],"video":null,"showInstructions":true,"showLeaderboard":true,"createdAt":"2024-07-12T17:00:38.968Z","publishedAt":"2024-07-12T17:02:08.568Z","updatedAt":"2024-07-12T17:02:08.546Z","contractId":95,"logo":null,"creatorId":"clyiy16a00000aw89kq4z6pd9","rateLimit":86400,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"archivedAt":null,"attributes":[{"id":128,"organizationId":"cly0d950o000310tjxcorg123","campaignId":"clyiy21mg0001b2nlbhmr01zx","title":"Direction","caption":null,"defaultImage":null,"hasImages":false,"createdAt":"2024-07-12T17:01:11.179Z","updatedAt":"2024-07-12T17:01:11.179Z","options":[{"id":323,"organizationId":"cly0d950o000310tjxcorg123","attributeId":128,"value":"{\"title\":\"Up only\",\"index\":0}"},{"id":324,"organizationId":"cly0d950o000310tjxcorg123","attributeId":128,"value":"{\"title\":\"Rekt\",\"index\":1}"}]}],"questions":[],"contract":{"id":95,"organizationId":"cly0d950o000310tjxcorg123","name":"The NFT","symbol":"THE_NFT","proxyAddress":"0xA78d08f33452Da9510Bde3dC2252d04bfA204cD3","implementationAddress":"0x3d054AC8B75473fc3CE151c208692E1B475864dD","metadataIpfsHash":null,"maxSupply":1000,"transferable":false,"points":0,"chainId":84532,"createdAt":"2024-07-12T17:01:31.488Z","updatedAt":"2025-03-06T18:45:37.756Z","abiId":1,"metadata":{"id":76,"organizationId":"cly0d950o000310tjxcorg123","nftContractId":95,"imageUrl":"ipfs://Qm.../image.png","description":"Cool","attributes":[{"value":"reid712959","trait_type":"Brand"},{"value":"Bug Test","trait_type":"Collection"}],"externalUrl":"https://app.example.com/campaign/clyiy21mg0001b2nlbhmr01zx","animationUrl":null}},"reward":{"id":103,"organizationId":"cly0d950o000310tjxcorg123","campaignId":"clyiy21mg0001b2nlbhmr01zx","points":10,"maxSupply":10000},"saved":false,"pointStats":{"maxSupply":10000,"perJourney":10,"journeyCount":1,"pointsRewarded":10,"pointsRemaining":9990}}}}}}}}},"put":{"summary":"Update draft campaign","description":"Updates a draft campaign with new metadata and configuration.","tags":["Campaigns"],"operationId":"replace","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"logo":{"description":"Optional campaign logo URL","example":"https://cdn.kiki.world/campaigns/logo.png","anyOf":[{"type":"string"},{"type":"null"}]},"video":{"description":"Optional campaign video URL","example":"https://youtu.be/launch-video","anyOf":[{"type":"string"},{"type":"null"}]},"showInstructions":{"description":"Whether to show participant instructions","example":true,"type":"boolean"},"showLeaderboard":{"description":"Whether to display the participant leaderboard","example":false,"type":"boolean"},"startDate":{"description":"Start date for the campaign (ISO8601)","example":"2024-01-01T00:00:00Z","anyOf":[{"type":"string"},{"type":"null"}]},"status":{"description":"Campaign status override","example":"PUBLISHED","type":"string","enum":["DRAFT","SUBMITTED","APPROVED","DENIED","PUBLISHED","ENDED","PAUSED","ARCHIVED"]},"endDate":{"description":"End date for the campaign (must be after startDate)","example":"2024-12-31T23:59:59Z","anyOf":[{"type":"string"},{"type":"null"}]},"maxParticipants":{"description":"Maximum number of participants allowed","example":1000,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"attributes":{"description":"Campaign attributes and variants","example":null,"anyOf":[{"description":"List of attributes for campaign submissions","minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"description":"Existing attribute identifier","example":17,"type":"number"},"title":{"description":"Attribute title shown in the campaign form","example":"Color","type":"string"},"hasImages":{"description":"Whether the attribute supports image selections","example":true,"type":"boolean"},"options":{"description":"Selectable options for the attribute","type":"array","items":{"type":"object","properties":{"id":{"description":"Existing attribute option identifier","example":42,"type":"number"},"value":{"description":"Visible value presented to participants","example":"Gold","type":"string"}},"required":["value"]}}},"required":["title","hasImages","options"]}},{"type":"null"}]},"questions":{"description":"Survey questions configured for the campaign","example":null,"anyOf":[{"description":"Survey questions associated with the campaign","minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"description":"Existing question identifier when editing surveys","example":55,"type":"number"},"type":{"description":"Question format controlling validation and presentation","example":"MULTIPLE_CHOICE","type":"string","enum":["FREEFORM","MULTIPLE_CHOICE","YES_NO"]},"title":{"description":"Prompt shown to respondents","example":"Which merch drop should launch first?","type":"string"},"media":{"description":"Optional media assets supporting the question prompt","example":[{"url":"https://cdn.kiki.world/campaigns/questions/merch.png","type":"image"}],"anyOf":[{"type":"array","items":{"type":"object","properties":{"url":{"description":"Publicly accessible URL pointing to the media asset","example":"https://cdn.kiki.world/assets/campaign-hero.jpg","type":"string","format":"uri"},"alt":{"description":"Optional descriptive text for accessibility","example":"Creator product hero image","type":"string"}},"required":["url"]}},{"type":"null"}]},"options":{"description":"Set of selectable answers when the type requires it","example":[{"value":"Crewneck Sweater"},{"value":"Denim Jacket"}],"minItems":1,"type":"array","items":{"type":"object","properties":{"value":{"description":"Option text presented to respondents","example":"Yes, count me in","type":"string","minLength":1}},"required":["value"]}}},"required":["type","title","media"]}},{"type":"null"}]},"reward":{"description":"Draft reward configuration for the campaign","anyOf":[{"type":"object","properties":{"points":{"description":"Reward points to issue to each participant","example":250,"type":"integer","minimum":0,"maximum":9007199254740991},"maxSupply":{"description":"Fixed reward point supply available for the campaign","example":10000,"type":"number","const":10000}},"required":["points","maxSupply"]},{"type":"null"}]},"hero":{"description":"Hero media assets for the campaign","example":null,"anyOf":[{"type":"array","items":{"type":"object","properties":{"url":{"description":"Publicly accessible URL pointing to the media asset","example":"https://cdn.kiki.world/assets/campaign-hero.jpg","type":"string","format":"uri"},"alt":{"description":"Optional descriptive text for accessibility","example":"Creator product hero image","type":"string"}},"required":["url"]}},{"type":"null"}]},"title":{"description":"Campaign title","example":"Aurora Album Launch","anyOf":[{"type":"string"},{"type":"null"}]},"description":{"description":"Campaign description","example":"Support the next album release.","anyOf":[{"type":"string"},{"type":"null"}]},"rateLimit":{"description":"Rate limit applied to participant interactions","example":86400,"type":"number","enum":[0,1892160000,86400,604800,2592000]}}}}}},"responses":{"200":{"description":"Draft campaign updated successfully","content":{"application/json":{"examples":{"success":{"summary":"Draft campaign updated","value":{"id":"clyiy21mg0001b2nlbhmr01zx","organizationId":"cly0d950o000310tjxcorg123","creatorId":"clyiy16a00000aw89kq4z6pd9","type":"MULTIVARIANT","status":"DRAFT","title":"Bug Test (Draft)","description":"working copy","startDate":null,"endDate":null,"maxParticipants":1000,"hero":null,"video":null,"showInstructions":true,"showLeaderboard":true,"publishedAt":null,"contractId":null,"logo":null,"rateLimit":86400,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"archivedAt":null,"createdAt":"2024-07-12T17:00:38.968Z","updatedAt":"2024-07-12T17:02:08.546Z","attributes":[],"questions":[],"contract":null,"reward":{"id":999,"organizationId":"cly0d950o000310tjxcorg123","campaignId":"clyiy21mg0001b2nlbhmr01zx","points":10,"maxSupply":10000}}}}}}}}},"patch":{"summary":"Update published campaign","description":"Updates limited fields on a published campaign.","tags":["Campaigns"],"operationId":"update","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"hero":{"description":"Primary media carousel shown at the top of the campaign page","example":[{"url":"https://cdn.kiki.world/campaigns/aurora/hero-1.jpg","type":"image"}],"minItems":1,"type":"array","items":{"type":"object","properties":{"url":{"description":"Publicly accessible URL pointing to the media asset","example":"https://cdn.kiki.world/assets/campaign-hero.jpg","type":"string","format":"uri"},"alt":{"description":"Optional descriptive text for accessibility","example":"Creator product hero image","type":"string"}},"required":["url"]}},"description":{"description":"Long-form narrative outlining the campaign goals","example":"Help Aurora design the next tour merch line for community voting.","anyOf":[{"description":"Non-empty trimmed string value","example":"Sample text","type":"string","minLength":1},{"type":"null"}]},"title":{"description":"Campaign title shown in listings and detail views","example":"Aurora World Tour Kickoff","type":"string","minLength":2,"maxLength":50},"showInstructions":{"description":"Toggle to display participation instructions post-launch","example":true,"type":"boolean"},"showLeaderboard":{"description":"Toggle to expose the campaign leaderboard to users","example":true,"type":"boolean"},"status":{"description":"Published campaign status change (e.g., pause)","example":"PAUSED","type":"string","enum":["DRAFT","SUBMITTED","APPROVED","DENIED","PUBLISHED","ENDED","PAUSED","ARCHIVED"]},"logo":{"description":"Updated serialized logo payload for the published campaign","example":"{\"url\":\"https://cdn.kiki.world/campaigns/aurora/logo.png\"}","anyOf":[{"type":"string"},{"type":"null"}]},"video":{"description":"Updated serialized video payload for the published campaign","example":"{\"url\":\"https://cdn.kiki.world/campaigns/aurora/promo.mp4\"}","anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Published campaign updated successfully","content":{"application/json":{"examples":{"success":{"summary":"Published campaign updated","value":{"id":"clyiy21mg0001b2nlbhmr01zx","organizationId":"cly0d950o000310tjxcorg123","creatorId":"clyiy16a00000aw89kq4z6pd9","type":"MULTIVARIANT","status":"PUBLISHED","title":"Bug Test","description":"is it a bug?","startDate":null,"endDate":null,"maxParticipants":1000,"hero":[{"alt":"Campaign Hero Image","url":"https://cdn.example.com/campaigns/clyiy21mg0001/hero.png"}],"video":null,"showInstructions":true,"showLeaderboard":true,"publishedAt":"2024-07-12T17:02:08.568Z","contractId":95,"logo":null,"rateLimit":86400,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"archivedAt":null,"createdAt":"2024-07-12T17:00:38.968Z","updatedAt":"2024-07-12T17:02:08.546Z","attributes":[{"id":128,"organizationId":"cly0d950o000310tjxcorg123","campaignId":"clyiy21mg0001b2nlbhmr01zx","title":"Direction","caption":null,"defaultImage":null,"hasImages":false,"createdAt":"2024-07-12T17:01:11.179Z","updatedAt":"2024-07-12T17:01:11.179Z","options":[{"id":323,"organizationId":"cly0d950o000310tjxcorg123","attributeId":128,"value":"{\"title\":\"Up only\",\"index\":0}"},{"id":324,"organizationId":"cly0d950o000310tjxcorg123","attributeId":128,"value":"{\"title\":\"Rekt\",\"index\":1}"}]}],"questions":[],"contract":{"id":95,"organizationId":"cly0d950o000310tjxcorg123","name":"The NFT","symbol":"THE_NFT","proxyAddress":"0xA78d08f33452Da9510Bde3dC2252d04bfA204cD3","implementationAddress":"0x3d054AC8B75473fc3CE151c208692E1B475864dD","metadataIpfsHash":null,"maxSupply":1000,"transferable":false,"points":0,"chainId":84532,"createdAt":"2024-07-12T17:01:31.488Z","updatedAt":"2025-03-06T18:45:37.756Z","abiId":1,"metadata":{"id":76,"organizationId":"cly0d950o000310tjxcorg123","nftContractId":95,"imageUrl":"ipfs://Qm.../image.png","description":"Cool","attributes":[{"value":"reid712959","trait_type":"Brand"},{"value":"Bug Test","trait_type":"Collection"}],"externalUrl":"https://app.example.com/campaign/clyiy21mg0001b2nlbhmr01zx","animationUrl":null}},"reward":{"id":103,"organizationId":"cly0d950o000310tjxcorg123","campaignId":"clyiy21mg0001b2nlbhmr01zx","points":10,"maxSupply":10000}}}}}}}}},"delete":{"summary":"Delete campaign","description":"Deletes the specified campaign after authorization.","tags":["Campaigns"],"operationId":"delete","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Campaign deleted successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaign deleted","value":{"message":"Campaign deleted successfully"}}}}}}}}},"/campaign/{id}/analytics":{"get":{"summary":"Get analytics for a campaign","description":"Returns engagement analytics and point statistics for a campaign.","tags":["Campaigns"],"operationId":"getAnalytics","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier to fetch analytics for","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier to fetch analytics for"}],"responses":{"200":{"description":"Analytics fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaign analytics","value":{"id":"cm3campaign123xyz","attributes":[{"id":1,"options":[{"id":1,"value":100,"meta":"Red"},{"id":2,"value":80,"meta":"Blue"}]}],"campaignJourneysCount":250,"pointStats":null}}}}}}}}},"/campaign/{id}/analytics/responses/growth":{"get":{"summary":"Get campaign responses growth data","description":"Returns response growth metrics across the selected time range.","tags":["Campaigns"],"operationId":"getAnalyticsResponsesGrowth","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"query","name":"timeRange","schema":{"description":"Time range window for response growth analytics","example":"1M","default":"ALL","type":"string","enum":["1W","1M","3M","1Y","ALL"]},"description":"Time range window for response growth analytics"}],"responses":{"200":{"description":"Response growth analytics fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Response growth data","value":[{"date":"2025-09-30","totalResponses":200},{"date":"2025-09-29","totalResponses":180}]}}}}}}}},"/campaign/{id}/analytics/participants":{"get":{"summary":"Get campaign participants","description":"Returns a paginated list of participants for the campaign.","tags":["Campaigns"],"operationId":"getAnalyticsParticipants","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier to fetch participants for","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier to fetch participants for"},{"in":"query","name":"page","schema":{"description":"Page number (0-indexed)","example":0,"type":"number","minimum":0},"description":"Page number (0-indexed)"},{"in":"query","name":"limit","schema":{"description":"Page size to return","example":20,"type":"number","minimum":0},"description":"Page size to return"}],"responses":{"200":{"description":"Participants fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaign participants","value":{"participants":{"results":[{"id":"cm3user123","username":"johndoe","avatarUrl":"https://example.com/avatar.jpg"}],"total":250}}}}}}}}}},"/campaign/{id}/analytics/participants/growth":{"get":{"summary":"Get campaign participants growth data","description":"Returns participant growth analytics across the specified time range.","tags":["Campaigns"],"operationId":"getAnalyticsParticipantsGrowth","parameters":[{"in":"path","name":"id","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"},{"in":"query","name":"timeRange","schema":{"description":"Time range window for growth analytics","example":"1M","default":"ALL","type":"string","enum":["1W","1M","3M","1Y","ALL"]},"description":"Time range window for growth analytics"}],"responses":{"200":{"description":"Participant growth analytics fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Participant growth data","value":[{"date":"2025-09-30T00:00:00.000Z","totalParticipants":150},{"date":"2025-09-29T00:00:00.000Z","totalParticipants":120}]}}}}}}}},"/campaign/{id}/analytics/participants/count":{"get":{"summary":"Get campaign participants count","description":"Returns total participants for the campaign.","tags":["Campaigns"],"operationId":"getAnalyticsParticipantsCount","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier to count participants for","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier to count participants for"}],"responses":{"200":{"description":"Participant count fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Participant count","value":{"totalParticipants":250}}}}}}}}},"/campaign/{id}/attributes":{"get":{"summary":"Get attributes for a campaign","description":"Returns the configured attribute list for the specified campaign.","tags":["Campaigns"],"operationId":"getAttributes","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier to fetch attributes for","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier to fetch attributes for"}],"responses":{"200":{"description":"Attributes fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaign attributes","value":[{"id":1,"organizationId":"cly0d950o000310tjxcorg123","title":"Color","hasImages":true,"caption":null,"campaignId":"cm3campaign123xyz","defaultImage":null,"createdAt":"2025-09-01T10:00:00.000Z","updatedAt":null}]}}}}}}}},"/campaign/{id}/survey":{"post":{"summary":"Submit campaign survey responses","description":"Validates and records participant survey responses for a campaign.","tags":["Campaigns"],"operationId":"createSurvey","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier to submit survey responses for","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier to submit survey responses for"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"description":"Identifier of the user submitting the survey responses","example":"clg0exampleuserid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"responses":{"description":"Survey responses submitted by the participant","example":[{"questionId":1,"answer":"Single answer response"},{"questionId":2,"answer":["Multiple","choice","answers"]}],"minItems":1,"type":"array","items":{"type":"object","properties":{"questionId":{"description":"Identifier of the survey question","example":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"answer":{"description":"Participant response to the survey question","example":"Single answer response","anyOf":[{"description":"Non-empty trimmed string value","example":"Sample text","type":"string","minLength":1},{"description":"Multiple choice answers when applicable","example":["Choice A","Choice B"],"minItems":1,"type":"array","items":{"description":"Non-empty trimmed string value","example":"Sample text","type":"string","minLength":1}}]}},"required":["questionId","answer"]}}},"required":["userId","responses"]}}}},"responses":{"200":{"description":"Survey responses recorded successfully","content":{"application/json":{"examples":{"success":{"summary":"Survey submitted","value":{"ok":true}}}}}}}}},"/campaign/{id}/survey/report":{"get":{"summary":"Get campaign survey report","description":"Returns aggregated survey analytics for the specified campaign.","tags":["Campaigns"],"operationId":"getSurveyReport","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier to retrieve the survey report for","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier to retrieve the survey report for"}],"responses":{"200":{"description":"Survey report generated successfully","content":{"application/json":{"examples":{"success":{"summary":"Survey report data","value":{"campaignId":"cm3campaign123xyz","participants":{"total":150,"participants":[{"user":{"id":"cm3user123","username":"johndoe","avatarUrl":"https://example.com/avatar.jpg"}}]},"last24HourResponsesCount":25,"report":[{"questionId":1,"type":"FREEFORM","title":"What is your favorite color?","analytics":{"responsesCount":150,"breakdown":[{"option":"Blue","count":45,"participants":[{"username":"janedoe","avatarUrl":"https://example.com/avatar2.jpg","journeyId":2}]}]}}]}}}}}}}}},"/campaign/{id}/publish":{"patch":{"summary":"Publish a campaign","description":"Transitions a campaign to the published state after validating Merchant permissions.","tags":["Campaigns"],"operationId":"publish","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier to publish","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier to publish"}],"requestBody":{"content":{"application/json":{"schema":{"description":"Optional campaign publication requirements","example":{"requiresReview":true},"type":"object","properties":{"requiresReview":{"description":"Whether this campaign requires admin review before publication","example":true,"default":false,"type":"boolean"}}}}}},"responses":{"200":{"description":"Campaign published successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaign now published","value":{"id":"cm3campaign123xyz","organizationId":"cly0d950o000310tjxcorg123","creatorId":"cm3creator456","type":"SWIPE","status":"PUBLISHED","title":"Summer Collection Drop","description":"Vote on your favorite designs from our summer collection","startDate":"2025-09-30T10:00:00.000Z","endDate":"2025-12-31T23:59:59.000Z","maxParticipants":10000,"hero":[{"url":"https://example.com/hero.jpg","type":"image"}],"video":"https://example.com/promo.mp4","showInstructions":true,"showLeaderboard":true,"publishedAt":"2025-09-30T10:00:00.000Z","contractId":123,"logo":"https://example.com/logo.png","rateLimit":0,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"archivedAt":null,"createdAt":"2025-09-01T10:00:00.000Z","updatedAt":"2025-09-30T10:00:00.000Z"}}}}}}}}},"/campaign/{id}/nft":{"put":{"summary":"Update campaign NFT configuration","description":"Updates the NFT metadata associated with a campaign.","tags":["Campaigns"],"operationId":"replaceNft","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier whose NFT configuration will be updated","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier whose NFT configuration will be updated"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Name of the NFT","example":"My NFT","type":"string"},"description":{"description":"Description of the NFT","example":"This is my NFT","type":"string"},"externalUrl":{"description":"External URL of the NFT","example":"https://example.com","type":"string","format":"uri"},"points":{"description":"Points the NFT is worths","example":100,"type":"number","exclusiveMinimum":0},"imageUrl":{"description":"Image URL of the NFT","example":"https://example.com/image.jpg","type":"string","format":"uri"},"animationUrl":{"description":"Animation URL of the NFT","example":"https://example.com/animation.mp4","type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Campaign NFT configuration updated successfully","content":{"application/json":{"examples":{"success":{"summary":"NFT configuration updated","value":{"id":"cm3campaign123xyz","organizationId":"cly0d950o000310tjxcorg123","creatorId":"cm3creator456","type":"SWIPE","status":"DRAFT","title":"Campaign with NFT","description":"Campaign with updated NFT configuration","startDate":"2025-10-01T00:00:00.000Z","endDate":"2025-12-31T23:59:59.000Z","maxParticipants":5000,"hero":[{"url":"https://example.com/hero.jpg","type":"image"}],"video":null,"showInstructions":true,"showLeaderboard":true,"publishedAt":null,"contractId":456,"logo":"https://example.com/logo.png","rateLimit":0,"intentSettlementEnabled":false,"taskSettlementEnabled":false,"taskVerificationMethod":"oracle","taskDurationSeconds":3600,"archivedAt":null,"createdAt":"2025-09-01T10:00:00.000Z","updatedAt":"2025-09-30T10:00:00.000Z"}}}}}}}}},"/campaign/{id}/submit":{"patch":{"summary":"Submit campaign for review","description":"Submits a draft campaign for admin review after validating ownership and schema compliance.","tags":["Campaigns"],"operationId":"updateSubmit","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier to submit for admin review","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier to submit for admin review"}],"responses":{"200":{"description":"Campaign submitted for review successfully","content":{"application/json":{"examples":{"success":{"summary":"Campaign submitted","value":{"ok":true}}}}}}}}},"/campaign/{id}/vote":{"post":{"summary":"Submit campaign votes","description":"Records participant votes for a campaign attribute set.","tags":["Campaigns"],"operationId":"vote","parameters":[{"in":"path","name":"id","schema":{"description":"Campaign identifier to submit votes for","example":"clg0examplecampaignid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Campaign identifier to submit votes for"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"description":"Identifier of the user submitting the vote","example":"clg0exampleuserid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"votes":{"description":"List of attribute votes to record","example":[{"attributeId":1,"optionId":2},{"attributeId":3,"optionId":[4,5]}],"minItems":1,"type":"array","items":{"type":"object","properties":{"attributeId":{"description":"Identifier of the campaign attribute being voted on","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"optionId":{"description":"Selected option identifier(s) for the attribute","example":2,"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"minItems":1,"type":"array","items":{"type":"integer","minimum":0,"maximum":9007199254740991}}]}},"required":["attributeId","optionId"]}}},"required":["userId","votes"]}}}},"responses":{"200":{"description":"Votes recorded successfully","content":{"application/json":{"examples":{"success":{"summary":"Votes submitted","value":{"message":"Votes recorded successfully"}}}}}}}}},"/search":{"get":{"summary":"Search entities with query parameters","description":"Searches across multiple entity types (campaigns, Merchants, users, products, rewards) based on a query string. Optionally filter by entity type and customize ordering.","tags":["Search"],"operationId":"search","parameters":[{"in":"query","name":"query","schema":{"description":"Search query string","example":"limited edition sneakers","type":"string","minLength":1},"required":true,"description":"Search query string"},{"in":"query","name":"type","schema":{"description":"Entity type to search within (if omitted, searches all types)","example":"product","type":"string","enum":["campaign","creator","user","product","reward"]},"description":"Entity type to search within (if omitted, searches all types)"},{"in":"query","name":"orderBy","schema":{"description":"Sort field and direction in format \"field_direction\" (e.g., \"name_asc\", \"createdAt_desc\")","example":"name_asc","type":"string"},"description":"Sort field and direction in format \"field_direction\" (e.g., \"name_asc\", \"createdAt_desc\")"},{"in":"query","name":"page","schema":{"description":"Page number for pagination","example":1,"default":1,"type":"integer","minimum":1,"maximum":9007199254740991},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"description":"Number of results per page","example":10,"default":10,"type":"integer","minimum":1,"maximum":9007199254740991},"description":"Number of results per page"}],"responses":{"200":{"description":"Search results fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful search","value":{"results":[{"type":"product","data":{"id":"cm3prod123","organizationId":"cly0d950o000310tjxcorg123","name":"Limited Edition Sneakers","description":"Exclusive collector sneakers","type":"PHYSICAL","price":15000,"supply":100,"maxDiscount":0,"pointEligibility":"ANY","status":"PUBLISHED","createdAt":"2025-09-15T10:00:00.000Z","updatedAt":"2025-09-20T12:30:00.000Z","logo":"https://example.com/sneakers.jpg","slug":"limited-edition-sneakers","subcategoryId":1,"allowedPointSources":[],"archivedAt":null,"shopifyProductId":null,"shippingType":"FLAT_RATE","merchantId":"cm3creatorid456"}},{"type":"creator","data":{"id":"cm3creator456","organizationId":"cly0d950o000310tjxcorg123","avatarUrl":"https://example.com/avatar.jpg","displayName":"Sneaker Collector","slug":"sneaker-collector","description":"Exclusive sneaker drops","heroUrl":null,"streamChatToken":null,"flatShippingRate":null,"pointsAccepted":"SELF","roles":["PUBLISHER"],"stripeOnboardingReminderSentAt":null,"stripeOnboardingReminderClaimedUntil":null,"createdAt":"2025-01-01T00:00:00.000Z","updatedAt":"2025-09-01T00:00:00.000Z"}}],"page":1,"limit":10,"total":2}}}}}}}}},"/companion/sessions/{userId}/balance":{"get":{"summary":"Get a user's Sage Sessions balance","description":"Returns the current Sessions balance, next free-tier refresh timestamp, recent Credit Grants, and enrollment state.","tags":["Companion - Sessions"],"operationId":"getBalance","parameters":[{"in":"path","name":"userId","schema":{"description":"Podium user ID","type":"string","minLength":1},"required":true,"description":"Podium user ID"}],"responses":{"200":{"description":"Sessions balance + recent grants","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"number"},"nextFreeRefreshAt":{"type":"string"},"recentGrants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string","enum":["paid","promotional"]},"amountCents":{"description":"Original USD amount in cents","type":"number"},"sessionsGranted":{"type":"number"},"estimatedRemainingSessions":{"description":"Upper-bound estimate. Stripe does not yet expose per-grant remaining balance — only the aggregate via creditBalanceSummary. Use SessionBalance.balance for the authoritative user-visible total.","type":"number"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"source":{"type":"string","enum":["FREE_DAILY","POCKET_PACK","SAGE_PLUS_MIGRATION","ADMIN_GRANT","X402_USDC","UNKNOWN"]}},"required":["id","category","amountCents","sessionsGranted","estimatedRemainingSessions","expiresAt","createdAt","source"],"additionalProperties":false}},"enrolled":{"type":"boolean"}},"required":["balance","nextFreeRefreshAt","recentGrants","enrolled"],"additionalProperties":false}}}},"404":{"description":"User not found"}}}},"/companion/sessions/{userId}/transactions":{"get":{"summary":"List a user's Sage Sessions Credit Grant history","description":"Paginated list of Credit Grants for the user (free daily refreshes, paid Pocket Packs, promotional grants). Sourced live from Stripe.","tags":["Companion - Sessions"],"operationId":"getTransactions","parameters":[{"in":"path","name":"userId","schema":{"description":"Podium user ID","type":"string","minLength":1},"required":true,"description":"Podium user ID"},{"in":"query","name":"cursor","schema":{"description":"Stripe cursor — pass the previous response's `nextCursor`","type":"string"},"description":"Stripe cursor — pass the previous response's `nextCursor`"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated Credit Grant history","content":{"application/json":{"schema":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string","enum":["paid","promotional"]},"amountCents":{"description":"Original USD amount in cents","type":"number"},"sessionsGranted":{"type":"number"},"estimatedRemainingSessions":{"description":"Upper-bound estimate. Stripe does not yet expose per-grant remaining balance — only the aggregate via creditBalanceSummary. Use SessionBalance.balance for the authoritative user-visible total.","type":"number"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"source":{"type":"string","enum":["FREE_DAILY","POCKET_PACK","SAGE_PLUS_MIGRATION","ADMIN_GRANT","X402_USDC","UNKNOWN"]}},"required":["id","category","amountCents","sessionsGranted","estimatedRemainingSessions","expiresAt","createdAt","source"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"}},"required":["grants","nextCursor","hasMore"],"additionalProperties":false}}}}}}},"/companion/sessions/checkout":{"post":{"summary":"Create a Stripe Checkout Session for a Sage Pocket Pack","description":"Returns a hosted Stripe Checkout URL for the requested Pocket Pack (10 / 50 / 150 Sessions). Checkout supports cards, Apple Pay, Link, and Cash App. The Pocket Pack Credit Grant is minted on the `invoice.paid` webhook.","tags":["Companion - Sessions"],"operationId":"checkout","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"description":"Podium user ID","type":"string","minLength":1},"packSize":{"description":"Number of Sessions in the Pocket Pack","anyOf":[{"type":"number","const":10},{"type":"number","const":50},{"type":"number","const":150}]},"email":{"description":"Customer email (used when creating a new Stripe Customer)","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["userId","packSize"]}}}},"responses":{"200":{"description":"Checkout session URL + id"},"400":{"description":"Invalid pack size"},"500":{"description":"Stripe price IDs not configured"}}}},"/companion/creator":{"get":{"summary":"Get products curated by a creator","description":"Returns paginated ProductCatalogItems linked to a creator's resolvedProductIds, sorted by quality score. Use cursor/limit for pagination.","tags":["Companion"],"operationId":"listCreator","parameters":[{"in":"path","name":"handle","schema":{"description":"Creator handle","example":"cosmopolitan","type":"string","minLength":1},"required":true,"description":"Creator handle"},{"in":"query","name":"cursor","schema":{"description":"Cursor for pagination (product id)","type":"string"},"description":"Cursor for pagination (product id)"},{"in":"query","name":"limit","schema":{"description":"Items per page (max 50)","default":20,"type":"integer","minimum":1,"maximum":50},"description":"Items per page (max 50)"}],"responses":{"200":{"description":"Creator products returned successfully"},"404":{"description":"Creator not found or not active"}}}},"/companion/interactions":{"get":{"summary":"Get user product interactions","description":"Returns all product interactions for a given user, with product details included.","tags":["Companion"],"operationId":"listInteractions","parameters":[{"in":"path","name":"userId","schema":{"description":"Podium user ID","type":"string"},"required":true,"description":"Podium user ID"}],"responses":{"200":{"description":"Interactions returned successfully"}}},"post":{"summary":"Record a product interaction","description":"Records a user interaction (rank up, rank down, skip, purchased, etc.) with a product catalog item.","tags":["Companion"],"operationId":"createInteractions","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"description":"Podium user ID","example":"clg0userId","type":"string"},"productId":{"description":"Product catalog item ID","example":"clg0productId","type":"string"},"action":{"description":"Interaction action type","example":"RANK_UP","type":"string","enum":["RANK_UP","RANK_DOWN","SKIP","PURCHASED","PURCHASE_INTENT","NUDGE_OPENED"]},"score":{"description":"Optional normalized relevance score (0-1)","example":0.85,"type":"number","minimum":0,"maximum":1}},"required":["userId","productId","action"]}}}},"responses":{"200":{"description":"Interaction recorded successfully"}}}},"/companion/rewards":{"get":{"summary":"Get reward balance","description":"Returns the claimable reward balance for a user, including points, USDC conversion, and claim eligibility.","tags":["Companion"],"operationId":"listRewards","parameters":[{"in":"path","name":"userId","schema":{"description":"Podium user ID","type":"string"},"required":true,"description":"Podium user ID"}],"responses":{"200":{"description":"Reward balance returned successfully"}}},"post":{"summary":"Claim USDC reward","description":"Claims accumulated reward points as USDC on World Chain. Rate limited to 1 claim per user per day. Platform org access required.","tags":["Companion"],"operationId":"createRewards","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"description":"Podium user ID","type":"string"},"walletAddress":{"description":"World wallet address to receive USDC","type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"required":["userId","walletAddress"]}}}},"responses":{"200":{"description":"Claim processed successfully"},"400":{"description":"Insufficient points or invalid request"},"403":{"description":"Platform organization access required"},"429":{"description":"Daily claim limit reached"},"503":{"description":"Rewards disabled or treasury insufficient"}}}},"/companion/agent":{"get":{"summary":"Get chat history","description":"Returns the conversation history for the given user from the hot Redis store (24h TTL). Verifies user exists within the authenticated organization before returning.","tags":["Companion"],"operationId":"listAgent","parameters":[{"in":"path","name":"userId","schema":{"description":"Podium user ID to fetch chat history for","type":"string"},"required":true,"description":"Podium user ID to fetch chat history for"}],"responses":{"200":{"description":"Array of chat messages (id, role, content, timestamp)"},"404":{"description":"User not found"}}},"post":{"summary":"Chat with companion agent","description":"Send a message to the conversational companion agent. Returns an AI response with optional product cards.","tags":["Companion"],"operationId":"createAgent","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"description":"The Podium user ID (cuid2)","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"message":{"description":"The user message to send to the agent","type":"string","minLength":1,"maxLength":4000},"config":{"description":"Optional agent configuration overrides for persona, tools, model","type":"object","properties":{"persona":{"type":"object","properties":{"name":{"type":"string"},"vertical":{"type":"string"},"tone":{"type":"string"}}},"rules":{"type":"array","items":{"type":"string"}},"enabledTools":{"type":"array","items":{"type":"string"}},"model":{"type":"string"},"maxHistory":{"type":"number"},"surface":{"type":"string","enum":["telegram_bot","telegram_miniapp","web"]}}}},"required":["userId","message"]}}}},"responses":{"200":{"description":"Agent response with message and optional products"},"400":{"description":"Invalid request body"},"500":{"description":"Agent processing error"}}}},"/companion/world/nonce":{"post":{"summary":"Issue a server-side nonce for World Mini App walletAuth","description":"Returns a single-use nonce the World Mini App can pass to MiniKit.commands.walletAuth({ nonce }). The nonce is stored in Redis with a 5-minute TTL and consumed when the SIWE signature is verified server-side during World user creation.","tags":["Companion"],"operationId":"createWorldNonce","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Nonce issued. Body: `{ nonce: string, expiresInSeconds: number }`."}}}},"/companion/orders":{"get":{"summary":"List companion orders for a user","description":"Returns all companion concierge orders for a given user, newest first.","tags":["Companion"],"operationId":"listOrders","parameters":[{"in":"path","name":"userId","schema":{"description":"Podium user ID","type":"string"},"required":true,"description":"Podium user ID"}],"responses":{"200":{"description":"Orders returned successfully"}}},"post":{"summary":"Create a companion concierge order","description":"Creates a new order for a product. The order starts in PENDING_PAYMENT status and must be paid via x402 before fulfillment begins.","tags":["Companion"],"operationId":"createOrders","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"description":"Podium user ID","type":"string"},"productId":{"description":"Product catalog item ID","type":"string"},"shippingAddress":{"description":"Shipping address (optional for Stripe checkout — Stripe collects it)","type":"object","properties":{"street":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1},"zip":{"type":"string","minLength":1},"country":{"default":"US","type":"string","minLength":1}},"required":["street","city","state","zip"]},"email":{"description":"Contact email (optional for Stripe checkout — Stripe collects it)","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["userId","productId"]}}}},"responses":{"200":{"description":"Order created successfully"}}},"patch":{"summary":"Update companion order status","description":"Updates the status of a companion order (admin/fulfillment use).","tags":["Companion"],"operationId":"updateOrders","parameters":[{"in":"path","name":"orderId","schema":{"description":"Companion order ID","type":"string"},"required":true,"description":"Companion order ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"New order status","type":"string","enum":["PENDING_PAYMENT","PAID","FULFILLING","SHIPPED","DELIVERED","CANCELLED","REFUNDED"]},"fulfillmentNotes":{"description":"Optional fulfillment notes","type":"string"},"trackingNumber":{"description":"Carrier tracking number","type":"string","maxLength":191},"trackingUrl":{"description":"Carrier tracking URL","type":"string","maxLength":500,"format":"uri"}},"required":["status"]}}}},"responses":{"200":{"description":"Order status updated"}}}},"/companion/user":{"get":{"summary":"Find Podium user by Telegram ID","description":"Looks up the Podium user created by a Telegram bot via the synthetic email pattern `tg_{telegramId}@{app}.podium.app`. When `?app` is provided, matches exactly; otherwise falls back to prefix match with latest-created tiebreaker. Optionally links a real Privy DID if provided via ?privyId query param.","tags":["companion"],"operationId":"listUser","parameters":[{"in":"path","name":"telegramId","schema":{"description":"Telegram user ID","example":"5125110390","type":"string"},"required":true,"description":"Telegram user ID"},{"in":"query","name":"privyId","schema":{"description":"Real Privy DID to link to this user","example":"did:privy:cm8roswbc00rnvo2b7n2x8cql","type":"string"},"description":"Real Privy DID to link to this user"},{"in":"query","name":"app","schema":{"description":"Bot app name for exact email match (e.g. \"clone-agents\", \"beauty-companion\")","example":"clone-agents","type":"string"},"description":"Bot app name for exact email match (e.g. \"clone-agents\", \"beauty-companion\")"}],"responses":{"200":{"description":"OK"}}}},"/companion/profile":{"get":{"summary":"Get user intent profile","description":"Returns the shopping companion intent profile for the specified user.","tags":["Companion"],"operationId":"listProfile","parameters":[{"in":"path","name":"userId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"responses":{"200":{"description":"Intent profile returned successfully"},"404":{"description":"Intent profile not found"}}},"post":{"summary":"Create or replace user intent profile","description":"Creates or fully replaces the shopping companion intent profile for the specified user.","tags":["Companion"],"operationId":"createProfile","parameters":[{"in":"path","name":"userId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"skinType":{"description":"Skin type classification","example":"Combination","type":"string","maxLength":50},"concerns":{"description":"Skin concerns the user wants to address","example":["Anti-aging","Hydration","SPF protection"],"type":"array","items":{"type":"string"}},"priceRange":{"description":"Preferred price range for products","example":{"min":25,"max":75},"type":"object","properties":{"min":{"type":"number","minimum":0},"max":{"type":"number","exclusiveMinimum":0}},"required":["min","max"]},"brands":{"description":"Brand affinities","example":["Tatcha","CeraVe"],"type":"array","items":{"type":"string"}},"avoidances":{"description":"Ingredients or properties to avoid","example":["fragrance","parabens"],"type":"array","items":{"type":"string"}},"agentSummary":{"description":"Agent-generated conversation summary for persistent memory","type":"string"},"lastConversationAt":{"description":"Timestamp of the last agent conversation","type":"string"},"meta":{"description":"Soft preferences and metadata (e.g. \"prefers minimalist routines\")","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quizCompletedAt":{"description":"Timestamp when the user completed the onboarding quiz","type":"string"}}}}}},"responses":{"200":{"description":"Intent profile created or updated"}}},"patch":{"summary":"Partially update user intent profile","description":"Partially updates the shopping companion intent profile. Used during quiz step-by-step saves.","tags":["Companion"],"operationId":"updateProfile","parameters":[{"in":"path","name":"userId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"skinType":{"description":"Skin type classification","example":"Combination","type":"string","maxLength":50},"concerns":{"description":"Skin concerns the user wants to address","example":["Anti-aging","Hydration","SPF protection"],"type":"array","items":{"type":"string"}},"priceRange":{"description":"Preferred price range for products","example":{"min":25,"max":75},"type":"object","properties":{"min":{"type":"number","minimum":0},"max":{"type":"number","exclusiveMinimum":0}},"required":["min","max"]},"brands":{"description":"Brand affinities","example":["Tatcha","CeraVe"],"type":"array","items":{"type":"string"}},"avoidances":{"description":"Ingredients or properties to avoid","example":["fragrance","parabens"],"type":"array","items":{"type":"string"}},"agentSummary":{"description":"Agent-generated conversation summary for persistent memory","type":"string"},"lastConversationAt":{"description":"Timestamp of the last agent conversation","type":"string"},"meta":{"description":"Soft preferences and metadata (e.g. \"prefers minimalist routines\")","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quizCompletedAt":{"description":"Timestamp when the user completed the onboarding quiz","type":"string"}}}}}},"responses":{"200":{"description":"Intent profile updated"}}}},"/companion/profile/{userId}/seed-from-creator":{"post":{"summary":"Seed user profile from a creator persona","description":"Clones a creator persona's taste profile into the user's intent profile, resolving their product catalog and awarding activation points.","tags":["Companion"],"operationId":"createProfileSeedFromCreator","parameters":[{"in":"path","name":"userId","schema":{"type":"string","minLength":1},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"creatorHandle":{"type":"string","minLength":1}},"required":["creatorHandle"]}}}},"responses":{"200":{"description":"Profile seeded successfully"},"404":{"description":"Creator persona not found or not active"}}}},"/companion/profile/{userId}/points":{"post":{"summary":"Award companion points to user","description":"Awards Podium Points to a user for shopping companion engagement (quiz steps, interactions).","tags":["Companion"],"operationId":"createProfilePoints","parameters":[{"in":"path","name":"userId","schema":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Globally unique cuid2 identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"description":"Points to award (must be positive)","example":10,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"details":{"description":"Metadata about the points award","example":{"source":"shopping-companion","action":"quiz_step","step":"skinType"},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["amount"]}}}},"responses":{"200":{"description":"Points awarded successfully"}}}},"/companion/profile/{userId}/routine":{"get":{"summary":"Get user skincare routine","description":"Retrieves the user's saved morning and evening skincare routine.","tags":["Companion"],"operationId":"listProfileRoutine","parameters":[{"in":"path","name":"userId","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Routine retrieved successfully"}}},"put":{"summary":"Save user skincare routine","description":"Persists morning and evening skincare routine steps to the user's intent profile.","tags":["Companion"],"operationId":"replaceProfileRoutine","parameters":[{"in":"path","name":"userId","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"morning":{"default":[],"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["Cleanse","Treat","Moisturize","Protect","Repair","Seal","Exfoliate","Tone"]},"productId":{"type":"string"},"productName":{"type":"string"},"brand":{"type":"string"},"price":{"type":"number"},"sageNote":{"type":"string"}},"required":["role","productName","brand"]}},"evening":{"default":[],"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["Cleanse","Treat","Moisturize","Protect","Repair","Seal","Exfoliate","Tone"]},"productId":{"type":"string"},"productName":{"type":"string"},"brand":{"type":"string"},"price":{"type":"number"},"sageNote":{"type":"string"}},"required":["role","productName","brand"]}}}}}}},"responses":{"200":{"description":"Routine saved successfully"}}}},"/companion/guest":{"post":{"summary":"Create guest session or convert guest to real user","description":"POST /session creates an anonymous guest user for try-before-signup. POST /convert merges guest chat history into an authenticated user account.","tags":["Companion"],"operationId":"companionGuestSession","responses":{"200":{"description":"Guest session created or conversion complete"},"400":{"description":"Invalid request body"},"404":{"description":"Guest or target user not found"}}}},"/companion/recommendations":{"get":{"summary":"Get personalized product recommendations","description":"Returns a ranked list of product recommendations for the given user, powered by Claude. Uses the user intent profile (skin type, concerns, price range, brand affinities) and interaction history to filter and rank products from the catalog.","tags":["Companion"],"operationId":"listRecommendations","parameters":[{"in":"path","name":"userId","schema":{"description":"Podium user ID to generate recommendations for","type":"string"},"required":true,"description":"Podium user ID to generate recommendations for"},{"in":"query","name":"count","schema":{"description":"Number of recommendations to return","example":5,"default":5,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"Number of recommendations to return"},{"in":"query","name":"category","schema":{"description":"Limit to a specific category","example":"moisturizer","type":"string"},"description":"Limit to a specific category"},{"in":"query","name":"domain","schema":{"description":"Limit to a specific domain","example":"beauty","type":"string","enum":["beauty","wellness","fashion","home","peptides"]},"description":"Limit to a specific domain"}],"responses":{"200":{"description":"Ranked product recommendations returned successfully"},"404":{"description":"User not found"}}}},"/companion/products":{"get":{"summary":"List product catalog items","description":"Returns paginated product catalog items with optional filters for category, brand, price range, and search.","tags":["Companion"],"operationId":"listProducts","parameters":[{"in":"query","name":"domain","schema":{"description":"Filter by domain","example":"beauty","type":"string","enum":["beauty","wellness","fashion","home","peptides"]},"description":"Filter by domain"},{"in":"query","name":"category","schema":{"description":"Filter by category","example":"skincare","type":"string"},"description":"Filter by category"},{"in":"query","name":"brand","schema":{"description":"Filter by brand","example":"CeraVe","type":"string"},"description":"Filter by brand"},{"in":"query","name":"minPrice","schema":{"description":"Minimum price","example":10,"type":"number","minimum":0},"description":"Minimum price"},{"in":"query","name":"maxPrice","schema":{"description":"Maximum price","example":100,"type":"number","exclusiveMinimum":0},"description":"Maximum price"},{"in":"query","name":"inStock","schema":{"description":"Filter in-stock only","example":true,"type":"boolean"},"description":"Filter in-stock only"},{"in":"query","name":"search","schema":{"description":"Search name/brand","example":"moisturizer","type":"string"},"description":"Search name/brand"},{"in":"query","name":"limit","schema":{"description":"Results per page","example":20,"default":20,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"Results per page"},{"in":"query","name":"offset","schema":{"description":"Offset","example":0,"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"description":"Offset"}],"responses":{"200":{"description":"Product list returned successfully"}}},"post":{"summary":"Create a product catalog item","description":"Adds a new product to the shopping companion catalog.","tags":["Companion"],"operationId":"createProducts","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Product name","example":"CeraVe Moisturizing Cream","type":"string","maxLength":500},"brand":{"description":"Brand name","example":"CeraVe","type":"string","maxLength":191},"category":{"description":"Product category","example":"moisturizer","type":"string","maxLength":191},"price":{"description":"Price in currency","example":18.99,"type":"number","exclusiveMinimum":0},"currency":{"description":"Currency code","example":"USD","default":"USD","type":"string","maxLength":10},"imageUrl":{"description":"Product image URL","anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"productUrl":{"description":"Purchase/product page URL","example":"https://cerave.com/moisturizing-cream","type":"string","format":"uri"},"openGraphData":{"description":"Open Graph metadata","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"inStock":{"description":"Whether the product is in stock","default":true,"type":"boolean"}},"required":["name","brand","category","price","productUrl"]}}}},"responses":{"200":{"description":"Product created successfully"}}}},"/for-you/creators":{"get":{"summary":"Get personalized creators for user","description":"Returns a list of recommended Merchants for the authenticated user based on their interests.","tags":["For You"],"operationId":"listCreators","parameters":[{"in":"query","name":"userId","schema":{"description":"Unique identifier of the user","example":"clg0exampleuserid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Unique identifier of the user"}],"responses":{"200":{"description":"Personalized Merchants fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful personalized creators","value":[{"id":"cm3creator123","avatarUrl":"https://example.com/avatar1.jpg","displayName":"Cool Creator","slug":"cool-creator","followersCount":1250},{"id":"cm3creator456","avatarUrl":"https://example.com/avatar2.jpg","displayName":"Amazing Artist","slug":"amazing-artist","followersCount":3400}]}}}}}}}},"/for-you/feed":{"get":{"summary":"Get personalized feed for authenticated user","description":"Returns curated campaigns, products, and rewards tailored to the user, based on interests and history.","tags":["For You"],"operationId":"listFeed","parameters":[{"in":"query","name":"userId","schema":{"description":"Unique identifier of the user","example":"clg0exampleuserid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Unique identifier of the user"},{"in":"query","name":"interests","schema":{"description":"JSON-encoded array of interest identifiers","example":"[\"tech\",\"gaming\"]","default":"[]","type":"string"},"description":"JSON-encoded array of interest identifiers"},{"in":"query","name":"page","schema":{"description":"1-indexed page number for pagination","example":1,"default":1,"type":"number","minimum":0},"description":"1-indexed page number for pagination"}],"responses":{"200":{"description":"Personalized feed fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful personalized feed","value":{"campaigns":[],"products":[],"rewards":[],"interests":[1,3,5]}}}}}}}}},"/airdrop/{id}":{"get":{"summary":"Get airdrop by ID","description":"Returns details for a specific airdrop.","tags":["Airdrops"],"operationId":"get","parameters":[{"in":"path","name":"id","schema":{"description":"Numeric identifier of the airdrop to retrieve","example":123,"type":"number","exclusiveMinimum":0},"required":true,"description":"Numeric identifier of the airdrop to retrieve"}],"responses":{"200":{"description":"Airdrop fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":{"id":"cm3airdrop123","name":"Early Supporter Drop","rewardType":"POINTS","conditionType":"FANS","imageUrl":"https://example.com/airdrop.png","chainId":8453,"proxyAddress":"0x1234567890abcdef1234567890abcdef12345678","airdropId":123,"description":"Exclusive NFT for our early supporters","creatorId":"cm1creator456","delivered":[],"redeemed":[],"details":null}}}}}},"404":{"description":"Airdrop not found"}}}},"/airdrop/{id}/delivered":{"get":{"summary":"List delivered airdrop users","description":"Returns paginated users that have received the specified airdrop.","tags":["Airdrops"],"operationId":"getDelivered","parameters":[{"in":"path","name":"id","schema":{"description":"Numeric identifier of the airdrop whose delivered users are requested","example":123,"type":"number","exclusiveMinimum":0},"required":true,"description":"Numeric identifier of the airdrop whose delivered users are requested"},{"in":"query","name":"page","schema":{"description":"Page number for pagination","example":1,"default":1,"type":"number","exclusiveMinimum":0},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"description":"Number of items per page","example":10,"default":10,"type":"number","exclusiveMinimum":0},"description":"Number of items per page"}],"responses":{"200":{"description":"Delivered users fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":{"data":[{"id":"cm1user123","avatarUrl":"https://example.com/avatar1.jpg","username":"supporter1"},{"id":"cm1user456","avatarUrl":"https://example.com/avatar2.jpg","username":"supporter2"},{"id":"cm1user789","avatarUrl":"https://example.com/avatar3.jpg","username":"supporter3"}],"total":47}}}}}}}}},"/airdrop/{id}/redemption":{"get":{"summary":"List airdrop redemptions","description":"Returns redeemed NFT records for the specified airdrop.","tags":["Airdrops"],"operationId":"getRedemption","parameters":[{"in":"path","name":"id","schema":{"description":"Numeric identifier of the airdrop whose redemptions are requested","example":123,"type":"number","exclusiveMinimum":0},"required":true,"description":"Numeric identifier of the airdrop whose redemptions are requested"},{"in":"query","name":"timeRange","schema":{"description":"Time range for redemption analytics 1W, 1M, 3M, 1Y, ALL","example":"1W","default":"ALL","type":"string","enum":["1W","1M","3M","1Y","ALL"]},"description":"Time range for redemption analytics 1W, 1M, 3M, 1Y, ALL"}],"responses":{"200":{"description":"Redemptions fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval with time range data","value":[{"date":"2025-09-24","totalRedemptions":12},{"date":"2025-09-25","totalRedemptions":18},{"date":"2025-09-26","totalRedemptions":25},{"date":"2025-09-27","totalRedemptions":31},{"date":"2025-09-28","totalRedemptions":29},{"date":"2025-09-29","totalRedemptions":22},{"date":"2025-09-30","totalRedemptions":15}]}}}}}}}},"/intents":{"get":{"summary":"List intents for authenticated organization","description":"Returns a paginated list of reward intents, optionally filtered by status or campaign.","tags":["Intent"],"operationId":"list","responses":{"200":{"description":"Intents fetched successfully"}}},"post":{"summary":"Create a new reward intent","description":"Creates a USDC reward intent on-chain and records it in the database. Requires sufficient merchant treasury balance.","tags":["Intent"],"operationId":"create","responses":{"200":{"description":"Intent created successfully"}}},"patch":{"summary":"Update intent settlement settings","description":"Toggle intent-based settlement on or off for specific campaigns or all campaigns belonging to the organization.","tags":["Intent"],"operationId":"update","responses":{"200":{"description":"Settings updated successfully"}}}},"/universal-search":{"get":{"summary":"Universal search using FTS with optional LLM gating","description":"Performs full-text search across indexed content with optional LLM-assisted synthesis. Returns a compact list and optional suggestions.","tags":["Universal Search"],"operationId":"list","parameters":[{"in":"query","name":"query","schema":{"description":"Search query string","example":"limited edition sneakers","type":"string","minLength":1},"required":true,"description":"Search query string"},{"in":"query","name":"entityTypes","schema":{"description":"Comma-separated list of entity types to search","example":"product,campaign,creator","anyOf":[{"type":"array","items":{"type":"string","enum":["product","campaign","creator"]}},{"type":"string","minLength":1}]},"description":"Comma-separated list of entity types to search"},{"in":"query","name":"page","schema":{"description":"Page number for pagination","example":1,"default":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"description":"Number of results per page","example":20,"default":10,"type":"integer","exclusiveMinimum":0,"maximum":100},"description":"Number of results per page"},{"in":"query","name":"llm","schema":{"description":"Enable LLM-assisted answer synthesis with gating","example":true,"default":false,"type":"boolean"},"description":"Enable LLM-assisted answer synthesis with gating"},{"in":"query","name":"llmMode","schema":{"description":"Controls when LLM is used: auto (gated), force (always), off (never)","example":"auto","default":"auto","type":"string","enum":["auto","force","off"]},"description":"Controls when LLM is used: auto (gated), force (always), off (never)"},{"in":"query","name":"answer","schema":{"description":"Include LLM-generated answer when applicable","example":true,"default":true,"type":"boolean"},"description":"Include LLM-generated answer when applicable"},{"in":"query","name":"includeSuggestions","schema":{"description":"Include typed suggestions[] in the response alongside items","example":false,"default":false,"type":"boolean"},"description":"Include typed suggestions[] in the response alongside items"}],"responses":{"200":{"description":"Search results fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful search with results","value":{"success":true,"data":{"items":[{"id":"cm3searchresult123","entityType":"product","entityId":"cm3productid456","title":"Limited Edition Sneakers","url":"https://example.com/product/sneakers","snippet":"Exclusive limited edition sneakers · Premium quality","relevance":0.95,"metadata":{"slug":"limited-edition-sneakers","type":"PHYSICAL","brand":"example-brand","price":19900,"entity":"product"}},{"id":"cm3searchresult789","entityType":"campaign","entityId":"cm3campaignid321","title":"Summer Campaign 2025","url":null,"snippet":"Join our summer campaign and win exclusive rewards","relevance":0.88,"metadata":{"slug":"summer-2025","entity":"campaign","status":"PUBLISHED","creatorId":"cm3creatorid654"}}],"total":42,"page":1,"limit":10,"topScore":0.95,"suggestions":[]},"query":"limited edition sneakers"}}}}}}}}},"/universal-search/suggestions":{"get":{"summary":"Get search suggestions for autocomplete","description":"Returns typed search suggestions based on indexed content for autocomplete functionality.","tags":["Universal Search"],"operationId":"listSuggestions","parameters":[{"in":"query","name":"query","schema":{"description":"Partial query string for suggestions","example":"limited ed","type":"string","minLength":1},"required":true,"description":"Partial query string for suggestions"},{"in":"query","name":"limit","schema":{"description":"Maximum number of suggestions","example":10,"default":10,"type":"integer","exclusiveMinimum":0,"maximum":50},"description":"Maximum number of suggestions"}],"responses":{"200":{"description":"Search suggestions fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful suggestions retrieval","value":{"success":true,"data":{"suggestions":[{"type":"query","label":"limited edition sneakers","score":0.95},{"type":"query","label":"limited edition posters","score":0.88},{"type":"query","label":"limited edition prints","score":0.82}],"query":"limited ed"}}}}}}}}}},"/group/{id}":{"get":{"summary":"Get group details","description":"Retrieve details for a specific group","tags":["Group"],"operationId":"get","parameters":[{"in":"path","name":"id","schema":{"description":"Group identifier","example":"clg0examplegroupid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Group identifier"}],"responses":{"200":{"description":"Successfully retrieved group details","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":{"data":{"group":{"id":"cm3groupid123","name":"VIP Members","type":"USER","creatorId":"cm3creatorid456","createdAt":"2025-09-15T10:00:00.000Z","updatedAt":"2025-09-20T14:30:00.000Z","groupMembers":[{"id":"cm3user1","organizationId":"cly0d950o000310tjxcorg123","email":"user1@example.com","city":"San Francisco","state":"CA","username":"user1","displayName":null,"emailVerified":true,"avatarUrl":null,"bio":null,"streamChatToken":null,"createdAt":"2025-01-10T08:00:00.000Z","updatedAt":"2025-09-01T12:00:00.000Z","roles":[]},{"id":"cm3user2","organizationId":"cly0d950o000310tjxcorg123","email":"user2@example.com","city":"New York","state":"NY","username":"user2","displayName":null,"emailVerified":true,"avatarUrl":null,"bio":null,"streamChatToken":null,"createdAt":"2025-02-20T09:00:00.000Z","updatedAt":"2025-09-05T10:00:00.000Z","roles":[]}]}}}}}}}}}},"put":{"summary":"Update group","description":"Update group name and members","tags":["Group"],"operationId":"replace","parameters":[{"in":"path","name":"id","schema":{"description":"Group identifier","example":"clg0examplegroupid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Group identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"groupName":{"description":"Updated group name","example":"Updated Group Name","type":"string","minLength":1},"memberIds":{"description":"Updated list of member IDs","example":["clg0exampleuserid1","clg0exampleuserid2"],"minItems":1,"type":"array","items":{"description":"Globally unique cuid2 identifier","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"}}}}}}},"responses":{"200":{"description":"Successfully updated group","content":{"application/json":{"examples":{"success":{"summary":"Successful update","value":{"data":{"id":"cm3groupid123","organizationId":"cly0d950o000310tjxcorg123","name":"Updated VIP Members","type":"USER","creatorId":"cm3creatorid456","createdAt":"2025-09-15T10:00:00.000Z","updatedAt":"2025-09-30T16:00:00.000Z"}}}}}}}}},"delete":{"summary":"Delete group","description":"Delete a group","tags":["Group"],"operationId":"delete","parameters":[{"in":"path","name":"id","schema":{"description":"Group identifier","example":"clg0examplegroupid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"required":true,"description":"Group identifier"}],"responses":{"200":{"description":"Successfully deleted group","content":{"application/json":{"examples":{"success":{"summary":"Successful deletion","value":{"message":"Group deleted successfully"}}}}}}}}},"/nft/contract/{id}":{"get":{"summary":"Get NFT contract by ID","description":"Returns contract metadata for the specified NFT contract ID.","tags":["NFT Contract"],"operationId":"get","parameters":[{"in":"path","name":"id","schema":{"description":"Internal numeric identifier for the NFT contract","example":42,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"required":true,"description":"Internal numeric identifier for the NFT contract"}],"responses":{"200":{"description":"NFT contract fetched successfully","content":{"application/json":{"examples":{"success":{"value":{"id":42,"organizationId":"cly0d950o000310tjxcorg123","name":"Campaign Collection","symbol":"CAMPAIGN_001","proxyAddress":"0x1234567890abcdef1234567890abcdef12345678","implementationAddress":"0xabcdef1234567890abcdef1234567890abcdef12","metadataIpfsHash":"QmXYZ123abc...","maxSupply":1000,"transferable":true,"points":100,"chainId":8453,"createdAt":"2025-09-01T00:00:00.000Z","updatedAt":"2025-09-15T00:00:00.000Z","abiId":1}}}}}}}}},"/nft/{network}/{address}/creator":{"get":{"summary":"Get NFT creator for a contract","description":"Returns the Merchant information for the specified NFT contract.","tags":["NFT"],"operationId":"getCreator","parameters":[{"in":"path","name":"network","schema":{"description":"Blockchain network identifier","example":"eth-mainnet","type":"string","enum":["eth-mainnet","eth-goerli","eth-sepolia","eth-holesky","eth-hoodi","opt-mainnet","opt-goerli","opt-sepolia","arb-mainnet","arb-goerli","arb-sepolia","polygon-mainnet","polygon-mumbai","polygon-amoy","astar-mainnet","polygonzkevm-mainnet","polygonzkevm-testnet","polygonzkevm-cardona","base-mainnet","base-goerli","base-sepolia","zksync-mainnet","zksync-sepolia","shape-mainnet","shape-sepolia","linea-mainnet","linea-sepolia","fantom-mainnet","fantom-testnet","zetachain-mainnet","zetachain-testnet","arbnova-mainnet","blast-mainnet","blast-sepolia","mantle-mainnet","mantle-sepolia","scroll-mainnet","scroll-sepolia","gnosis-mainnet","gnosis-chiado","bnb-mainnet","bnb-testnet","avax-mainnet","avax-fuji","celo-mainnet","celo-alfajores","celo-baklava","metis-mainnet","opbnb-mainnet","opbnb-testnet","berachain-bartio","berachain-mainnet","berachain-bepolia","soneium-mainnet","soneium-minato","worldchain-mainnet","worldchain-sepolia","rootstock-mainnet","rootstock-testnet","flow-mainnet","flow-testnet","zora-mainnet","zora-sepolia","frax-mainnet","frax-sepolia","polynomial-mainnet","polynomial-sepolia","crossfi-mainnet","crossfi-testnet","apechain-mainnet","apechain-curtis","lens-mainnet","lens-sepolia","geist-mainnet","geist-polter","lumia-prism","lumia-testnet","unichain-mainnet","unichain-sepolia","sonic-mainnet","sonic-blaze","xmtp-testnet","abstract-mainnet","abstract-testnet","degen-mainnet","ink-mainnet","ink-sepolia","sei-mainnet","sei-testnet","ronin-mainnet","ronin-saigon","monad-testnet","settlus-septestnet","settlus-mainnet","solana-mainnet","solana-devnet","gensyn-testnet","superseed-mainnet","superseed-sepolia","tea-sepolia","anime-mainnet","anime-sepolia","story-mainnet","story-aeneid","megaeth-testnet","botanix-mainnet","botanix-testnet","humanity-mainnet","rise-testnet","hyperliquid-mainnet","hyperliquid-testnet","plasma-mainnet","plasma-testnet"]},"required":true,"description":"Blockchain network identifier"},{"in":"path","name":"address","schema":{"description":"Checksummed Ethereum address","example":"0x742d35Cc6634C0532925a3b844Bc454e4438f44e","type":"string"},"required":true,"description":"Checksummed Ethereum address"}],"responses":{"200":{"description":"NFT Merchant fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful creator retrieval","value":{"creator":{"id":"cm3creator123","organizationId":"cly0d950o000310tjxcorg123","displayName":"NFT Creator","slug":"nft-creator","avatarUrl":"https://example.com/creator-avatar.jpg","description":"Merchant of this NFT collection","heroUrl":null,"flatShippingRate":null,"streamChatToken":null,"pointsAccepted":"SELF","roles":["PUBLISHER"],"stripeOnboardingReminderSentAt":null,"stripeOnboardingReminderClaimedUntil":null,"createdAt":"2025-09-01T10:00:00.000Z","updatedAt":"2025-09-20T12:00:00.000Z"}}}}}}}}}},"/nft/{network}/{address}/owners":{"get":{"summary":"Get NFT owners for a contract","description":"Returns the owners of an NFT contract on the specified network in paginated form.","tags":["NFT"],"operationId":"getOwners","parameters":[{"in":"path","name":"address","schema":{"description":"Contract address for the NFT collection","example":"0x1234567890abcdef1234567890abcdef12345678","type":"string"},"required":true,"description":"Contract address for the NFT collection"},{"in":"path","name":"network","schema":{"description":"Blockchain network where the contract is deployed","example":"ethereum","type":"string","enum":["eth-mainnet","eth-goerli","eth-sepolia","eth-holesky","eth-hoodi","opt-mainnet","opt-goerli","opt-sepolia","arb-mainnet","arb-goerli","arb-sepolia","polygon-mainnet","polygon-mumbai","polygon-amoy","astar-mainnet","polygonzkevm-mainnet","polygonzkevm-testnet","polygonzkevm-cardona","base-mainnet","base-goerli","base-sepolia","zksync-mainnet","zksync-sepolia","shape-mainnet","shape-sepolia","linea-mainnet","linea-sepolia","fantom-mainnet","fantom-testnet","zetachain-mainnet","zetachain-testnet","arbnova-mainnet","blast-mainnet","blast-sepolia","mantle-mainnet","mantle-sepolia","scroll-mainnet","scroll-sepolia","gnosis-mainnet","gnosis-chiado","bnb-mainnet","bnb-testnet","avax-mainnet","avax-fuji","celo-mainnet","celo-alfajores","celo-baklava","metis-mainnet","opbnb-mainnet","opbnb-testnet","berachain-bartio","berachain-mainnet","berachain-bepolia","soneium-mainnet","soneium-minato","worldchain-mainnet","worldchain-sepolia","rootstock-mainnet","rootstock-testnet","flow-mainnet","flow-testnet","zora-mainnet","zora-sepolia","frax-mainnet","frax-sepolia","polynomial-mainnet","polynomial-sepolia","crossfi-mainnet","crossfi-testnet","apechain-mainnet","apechain-curtis","lens-mainnet","lens-sepolia","geist-mainnet","geist-polter","lumia-prism","lumia-testnet","unichain-mainnet","unichain-sepolia","sonic-mainnet","sonic-blaze","xmtp-testnet","abstract-mainnet","abstract-testnet","degen-mainnet","ink-mainnet","ink-sepolia","sei-mainnet","sei-testnet","ronin-mainnet","ronin-saigon","monad-testnet","settlus-septestnet","settlus-mainnet","solana-mainnet","solana-devnet","gensyn-testnet","superseed-mainnet","superseed-sepolia","tea-sepolia","anime-mainnet","anime-sepolia","story-mainnet","story-aeneid","megaeth-testnet","botanix-mainnet","botanix-testnet","humanity-mainnet","rise-testnet","hyperliquid-mainnet","hyperliquid-testnet","plasma-mainnet","plasma-testnet"]},"required":true,"description":"Blockchain network where the contract is deployed"}],"responses":{"200":{"description":"NFT owners fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful owners retrieval","value":{"data":[{"username":"user123","email":"user@example.com","avatarUrl":"https://example.com/avatar.jpg"},{"username":"collector456","email":"collector@example.com","avatarUrl":"https://example.com/avatar2.jpg"}],"total":45,"page":1,"limit":10}}}}}}}}},"/nft/{network}/{address}/{tokenId}":{"get":{"summary":"Get NFT details by token ID","description":"Returns metadata for a specific NFT given the network, contract address, and token ID.","tags":["NFT"],"operationId":"getByTokenId","parameters":[{"in":"path","name":"network","schema":{"description":"Blockchain network identifier","example":"eth-mainnet","type":"string","enum":["eth-mainnet","eth-goerli","eth-sepolia","eth-holesky","eth-hoodi","opt-mainnet","opt-goerli","opt-sepolia","arb-mainnet","arb-goerli","arb-sepolia","polygon-mainnet","polygon-mumbai","polygon-amoy","astar-mainnet","polygonzkevm-mainnet","polygonzkevm-testnet","polygonzkevm-cardona","base-mainnet","base-goerli","base-sepolia","zksync-mainnet","zksync-sepolia","shape-mainnet","shape-sepolia","linea-mainnet","linea-sepolia","fantom-mainnet","fantom-testnet","zetachain-mainnet","zetachain-testnet","arbnova-mainnet","blast-mainnet","blast-sepolia","mantle-mainnet","mantle-sepolia","scroll-mainnet","scroll-sepolia","gnosis-mainnet","gnosis-chiado","bnb-mainnet","bnb-testnet","avax-mainnet","avax-fuji","celo-mainnet","celo-alfajores","celo-baklava","metis-mainnet","opbnb-mainnet","opbnb-testnet","berachain-bartio","berachain-mainnet","berachain-bepolia","soneium-mainnet","soneium-minato","worldchain-mainnet","worldchain-sepolia","rootstock-mainnet","rootstock-testnet","flow-mainnet","flow-testnet","zora-mainnet","zora-sepolia","frax-mainnet","frax-sepolia","polynomial-mainnet","polynomial-sepolia","crossfi-mainnet","crossfi-testnet","apechain-mainnet","apechain-curtis","lens-mainnet","lens-sepolia","geist-mainnet","geist-polter","lumia-prism","lumia-testnet","unichain-mainnet","unichain-sepolia","sonic-mainnet","sonic-blaze","xmtp-testnet","abstract-mainnet","abstract-testnet","degen-mainnet","ink-mainnet","ink-sepolia","sei-mainnet","sei-testnet","ronin-mainnet","ronin-saigon","monad-testnet","settlus-septestnet","settlus-mainnet","solana-mainnet","solana-devnet","gensyn-testnet","superseed-mainnet","superseed-sepolia","tea-sepolia","anime-mainnet","anime-sepolia","story-mainnet","story-aeneid","megaeth-testnet","botanix-mainnet","botanix-testnet","humanity-mainnet","rise-testnet","hyperliquid-mainnet","hyperliquid-testnet","plasma-mainnet","plasma-testnet"]},"required":true,"description":"Blockchain network identifier"},{"in":"path","name":"address","schema":{"description":"Checksummed Ethereum address","example":"0x742d35Cc6634C0532925a3b844Bc454e4438f44e","type":"string"},"required":true,"description":"Checksummed Ethereum address"},{"in":"path","name":"tokenId","schema":{"description":"Token identifier for the NFT within the contract","example":123,"type":"number","minimum":0},"required":true,"description":"Token identifier for the NFT within the contract"}],"responses":{"200":{"description":"NFT details fetched successfully","content":{"application/json":{"examples":{"success":{"value":{"campaign":{"id":"cm3campaignid123","title":"Summer Campaign","description":"Join our summer campaign"},"reward":null,"network":"polygon-mainnet","contract":"0x1234567890abcdef1234567890abcdef12345678","tokenId":123,"name":"Campaign NFT #123","description":"Limited edition campaign NFT","imageUrl":"https://example.com/nft.jpg","isSpam":false,"traits":[{"traitType":"Rarity","value":"Legendary"}]}}}}}}}}},"/nft/{network}/{address}/{tokenId}/owner":{"get":{"summary":"Get NFT token owner information","description":"Returns paginated owners for a specific NFT token identified by network, contract address, and token ID.","tags":["NFT"],"operationId":"getOwner","parameters":[{"in":"path","name":"network","schema":{"description":"Blockchain network identifier","example":"eth-mainnet","type":"string","enum":["eth-mainnet","eth-goerli","eth-sepolia","eth-holesky","eth-hoodi","opt-mainnet","opt-goerli","opt-sepolia","arb-mainnet","arb-goerli","arb-sepolia","polygon-mainnet","polygon-mumbai","polygon-amoy","astar-mainnet","polygonzkevm-mainnet","polygonzkevm-testnet","polygonzkevm-cardona","base-mainnet","base-goerli","base-sepolia","zksync-mainnet","zksync-sepolia","shape-mainnet","shape-sepolia","linea-mainnet","linea-sepolia","fantom-mainnet","fantom-testnet","zetachain-mainnet","zetachain-testnet","arbnova-mainnet","blast-mainnet","blast-sepolia","mantle-mainnet","mantle-sepolia","scroll-mainnet","scroll-sepolia","gnosis-mainnet","gnosis-chiado","bnb-mainnet","bnb-testnet","avax-mainnet","avax-fuji","celo-mainnet","celo-alfajores","celo-baklava","metis-mainnet","opbnb-mainnet","opbnb-testnet","berachain-bartio","berachain-mainnet","berachain-bepolia","soneium-mainnet","soneium-minato","worldchain-mainnet","worldchain-sepolia","rootstock-mainnet","rootstock-testnet","flow-mainnet","flow-testnet","zora-mainnet","zora-sepolia","frax-mainnet","frax-sepolia","polynomial-mainnet","polynomial-sepolia","crossfi-mainnet","crossfi-testnet","apechain-mainnet","apechain-curtis","lens-mainnet","lens-sepolia","geist-mainnet","geist-polter","lumia-prism","lumia-testnet","unichain-mainnet","unichain-sepolia","sonic-mainnet","sonic-blaze","xmtp-testnet","abstract-mainnet","abstract-testnet","degen-mainnet","ink-mainnet","ink-sepolia","sei-mainnet","sei-testnet","ronin-mainnet","ronin-saigon","monad-testnet","settlus-septestnet","settlus-mainnet","solana-mainnet","solana-devnet","gensyn-testnet","superseed-mainnet","superseed-sepolia","tea-sepolia","anime-mainnet","anime-sepolia","story-mainnet","story-aeneid","megaeth-testnet","botanix-mainnet","botanix-testnet","humanity-mainnet","rise-testnet","hyperliquid-mainnet","hyperliquid-testnet","plasma-mainnet","plasma-testnet"]},"required":true,"description":"Blockchain network identifier"},{"in":"path","name":"address","schema":{"description":"Checksummed Ethereum address","example":"0x742d35Cc6634C0532925a3b844Bc454e4438f44e","type":"string"},"required":true,"description":"Checksummed Ethereum address"},{"in":"path","name":"tokenId","schema":{"description":"Token identifier for the NFT within the contract","example":123,"type":"number","minimum":0},"required":true,"description":"Token identifier for the NFT within the contract"},{"in":"query","name":"sort","schema":{"description":"Field name used for ordering results","example":"createdAt","default":"createdAt","type":"string"},"description":"Field name used for ordering results"},{"in":"query","name":"order","schema":{"description":"Sort direction when ordering results","example":"desc","default":"desc","type":"string","enum":["asc","desc"]},"description":"Sort direction when ordering results"},{"in":"query","name":"page","schema":{"description":"1-indexed page number","example":1,"default":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"1-indexed page number"},{"in":"query","name":"limit","schema":{"description":"Maximum number of records to return per page","example":25,"default":10,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"Maximum number of records to return per page"}],"responses":{"200":{"description":"NFT owners fetched successfully","content":{"application/json":{"examples":{"success":{"summary":"Successful token owners retrieval","value":{"data":[{"username":"nftowner","email":"owner@example.com","avatarUrl":"https://example.com/owner-avatar.jpg"}]}}}}}}}}},"/products":{"get":{"summary":"List products","description":"Retrieve a paginated list of products with optional category filtering","tags":["Product"],"operationId":"list","parameters":[{"in":"query","name":"userId","schema":{"description":"Optional user ID for personalized results","example":"clg0exampleid","type":"string","format":"cuid2","pattern":"^[0-9a-z]+$"},"description":"Optional user ID for personalized results"},{"in":"query","name":"page","schema":{"description":"Page number for pagination","example":1,"default":1,"type":"number","exclusiveMinimum":0},"description":"Page number for pagination"},{"in":"query","name":"limit","schema":{"description":"Number of products per page","example":20,"default":10,"type":"number","exclusiveMinimum":0},"description":"Number of products per page"},{"in":"query","name":"categories","schema":{"description":"Comma-separated list of category IDs to filter by","example":"1,2,3","type":"string"},"description":"Comma-separated list of category IDs to filter by"},{"in":"query","name":"sort","schema":{"description":"Sort order: \"recent\" (newest first) or \"popular\" (most sold first)","example":"popular","default":"recent","type":"string","enum":["recent","popular"]},"description":"Sort order: \"recent\" (newest first) or \"popular\" (most sold first)"}],"responses":{"200":{"description":"Successfully retrieved list of products","content":{"application/json":{"examples":{"success":{"summary":"Successful retrieval","value":{"data":[{"id":"cm3prod123xyz","name":"Limited Edition T-Shirt","description":"Exclusive merch from your favorite Merchant","type":"PHYSICAL","price":2999,"supply":100,"maxDiscount":500,"pointEligibility":"ENABLED","status":"PUBLISHED","logo":"https://storage.googleapis.com/bucket/product-logo.jpg","slug":"limited-edition-t-shirt","subcategoryId":3,"createdAt":"2025-09-15T10:00:00.000Z","updatedAt":"2025-09-28T15:30:00.000Z","media":{"id":42,"url":"https://storage.googleapis.com/bucket/product-image.jpg","order":1,"type":"IMAGE","productId":"cm3prod123xyz","createdAt":"2025-09-15T10:00:00.000Z"},"creatorProducts":[{"creatorId":"cm1creator456","productId":"cm3prod123xyz","id":"cm1creator456","displayName":"Cool Creator","avatarUrl":"https://storage.googleapis.com/bucket/avatar.jpg","slug":"cool-creator"}],"saved":false},{"id":"cm3prod789abc","name":"Digital Art Print","description":"High-resolution digital artwork","type":"DIGITAL","price":999,"supply":500,"maxDiscount":0,"pointEligibility":"DISABLED","status":"PUBLISHED","logo":"https://storage.googleapis.com/bucket/digital-logo.jpg","slug":"digital-art-print","subcategoryId":7,"createdAt":"2025-09-20T14:00:00.000Z","updatedAt":"2025-09-29T09:15:00.000Z","media":null,"creatorProducts":[{"creatorId":"cm2artist789","productId":"cm3prod789abc","id":"cm2artist789","displayName":"Digital Artist","avatarUrl":"https://storage.googleapis.com/bucket/artist-avatar.jpg","slug":"digital-artist"}],"saved":true}],"total":42,"page":1,"limit":10}}}}}}}}},"/products/lookup":{"post":{"summary":"Lookup product by URL","description":"Resolve any merchant product URL into a canonical product record.\n\nBehavior:\n- Follows known intermediaries (ShopMy redirects, Google Shopping) to the underlying retailer URL.\n- Returns the existing ProductCatalogItem if one matches the canonicalized URL.\n- On cache miss, optionally enriches via Firecrawl scrape and persists a new row.\n- Always returns a `purchaseMode` (x402_platform | stripe_platform | affiliate | external) and `canAgentCheckout` flag, so agents can decide how to proceed.\n- If Firecrawl cannot extract a product name, falls back to a hostname-based stub (`source: \"fallback\"`) so callers (e.g. Rye) that do their own merchant-side resolution can still proceed.","tags":["Products"],"operationId":"createLookup","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"Any merchant product URL (Amazon, Shopify, ShopMy, LTK, brand DTC site, …). Intermediaries (ShopMy redirects, Google Shopping) are followed automatically.","example":"https://www.sephora.com/product/the-ordinary-niacinamide-10-zinc-1-P427406","type":"string","format":"uri"},"enrich":{"description":"When true (default), runs a Firecrawl scrape on cache miss to populate name/brand/price/image. Set to false for fast, lookup-only calls.","default":true,"type":"boolean"},"persist":{"description":"When true (default), persists the resolved item to ProductCatalogItem. Set to false to preview without mutating the catalog.","default":true,"type":"boolean"}},"required":["url"]}}}},"responses":{"200":{"description":"Resolved product record","content":{"application/json":{"examples":{"cached":{"summary":"URL already in catalog","value":{"cached":true,"rewritten":false,"inputUrl":"https://www.sephora.com/product/the-ordinary-niacinamide-10-zinc-1-P427406","resolvedUrl":"https://sephora.com/product/the-ordinary-niacinamide-10-zinc-1-P427406","derivedRetailer":{"retailer":"sephora","retailerType":"AFFILIATE_PARTNER"},"item":{"id":"cm3prod123xyz","name":"Niacinamide 10% + Zinc 1%","brand":"The Ordinary","price":6.5,"productUrl":"https://sephora.com/product/the-ordinary-niacinamide-10-zinc-1-P427406","retailer":"sephora","retailerType":"AFFILIATE_PARTNER","purchaseMode":"affiliate","canAgentCheckout":false,"retailerDisplayName":"Sephora"}}},"createdViaShopMy":{"summary":"ShopMy URL rewritten and persisted","value":{"cached":false,"rewritten":true,"inputUrl":"https://shopmy.us/p/abc123","resolvedUrl":"https://www.sephora.com/product/the-ordinary-niacinamide-10-zinc-1-P427406","derivedRetailer":{"retailer":"sephora","retailerType":"AFFILIATE_PARTNER"},"item":{"id":"cm3newprod456","purchaseMode":"affiliate","canAgentCheckout":false}}}}}}},"400":{"description":"Invalid URL"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your Podium secret API key"}}}}