{
	"openapi": "3.1.0",
	"info": {
		"title": "Verosight API",
		"version": "1.0.0",
		"description": "Social media intelligence API. Access real-time data from X, Instagram, TikTok, Facebook, LinkedIn, YouTube, and news portals. Provides AI chat with tool-use, AI-powered recommendations, posts, comments, profiles, sentiment analysis, trending topics, engagement analytics, expert identification, semantic search, profile monitoring, and data export.",
		"contact": {
			"name": "Verosight Support",
			"url": "https://verosight.com/contact",
			"email": "support@verosight.com"
		},
		"termsOfService": "https://verosight.com/terms",
		"x-llms-txt": "https://verosight.com/llms.txt",
		"x-llms-full-txt": "https://verosight.com/llms-full.txt"
	},
	"servers": [
		{
			"url": "https://api.verosight.com",
			"description": "Production API"
		}
	],
	"security": [
		{ "apiKey": [] },
		{ "bearerAuth": [] }
	],
	"components": {
		"securitySchemes": {
			"apiKey": {
				"type": "apiKey",
				"in": "header",
				"name": "X-API-Key",
				"description": "API key with vlt_live_ or vlt_test_ prefix"
			},
			"bearerAuth": {
				"type": "http",
				"scheme": "bearer",
				"bearerFormat": "JWT",
				"description": "24-hour JWT obtained via POST /v1/auth/token"
			}
		},
		"schemas": {
			"Meta": {
				"type": "object",
				"properties": {
					"request_id": { "type": "string" },
					"credits_used": { "type": "integer" },
					"credits_remaining": { "type": "integer" }
				}
			},
			"Pagination": {
				"type": "object",
				"properties": {
					"next_cursor": { "type": "string", "nullable": true },
					"has_more": { "type": "boolean" },
					"total": { "type": "integer" }
				}
			},
			"Post": {
				"type": "object",
				"properties": {
					"id": { "type": "string" },
					"platform": { "type": "string", "enum": ["x", "instagram", "tiktok", "facebook", "linkedin", "youtube", "news"] },
					"profile_name": { "type": "string" },
					"content": { "type": "string" },
					"media_type": { "type": "string" },
					"likes": { "type": "integer" },
					"comments_count": { "type": "integer" },
					"shares": { "type": "integer" },
					"created_at": { "type": "string", "format": "date-time" }
				}
			},
			"Comment": {
				"type": "object",
				"properties": {
					"id": { "type": "string" },
					"platform": { "type": "string" },
					"post_id": { "type": "string" },
					"profile_name": { "type": "string" },
					"content": { "type": "string" },
					"likes": { "type": "integer" },
					"created_at": { "type": "string", "format": "date-time" }
				}
			},
			"Profile": {
				"type": "object",
				"properties": {
					"platform": { "type": "string" },
					"username": { "type": "string" },
					"display_name": { "type": "string" },
					"bio": { "type": "string" },
					"followers": { "type": "integer" },
					"following": { "type": "integer" },
					"is_verified": { "type": "boolean" },
					"profile_url": { "type": "string" }
				}
			},
			"SentimentResult": {
				"type": "object",
				"properties": {
					"total": { "type": "integer" },
					"positive": { "type": "integer" },
					"negative": { "type": "integer" },
					"neutral": { "type": "integer" },
					"positive_pct": { "type": "number" },
					"negative_pct": { "type": "number" },
					"neutral_pct": { "type": "number" },
					"samples": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }
				}
			},
			"Error": {
				"type": "object",
				"properties": {
					"error": {
						"type": "object",
						"properties": {
							"code": { "type": "string" },
							"message": { "type": "string" }
						}
					},
					"meta": { "$ref": "#/components/schemas/Meta" }
				}
			}
		},
		"parameters": {
			"platform": {
				"name": "platform",
				"in": "query",
				"schema": { "type": "string", "enum": ["x", "instagram", "tiktok", "facebook", "linkedin", "youtube", "news"] },
				"description": "Filter by social media platform (case-insensitive)"
			},
			"limit": {
				"name": "limit",
				"in": "query",
				"schema": { "type": "integer", "default": 20, "maximum": 100 },
				"description": "Number of results to return"
			},
			"cursor": {
				"name": "cursor",
				"in": "query",
				"schema": { "type": "string" },
				"description": "Pagination cursor from previous response"
			},
			"days": {
				"name": "days",
				"in": "query",
				"schema": { "type": "integer", "default": 7 },
				"description": "Number of days to look back"
			}
		}
	},
	"paths": {
		"/v1/auth/token": {
			"post": {
				"operationId": "exchangeToken",
				"summary": "Exchange API key for JWT (0 credits)",
				"description": "Exchange your API key for a 24-hour JWT Bearer token.",
				"security": [{ "apiKey": [] }],
				"responses": {
					"200": {
						"description": "JWT token",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "object",
											"properties": {
												"token": { "type": "string" },
												"expires_at": { "type": "string", "format": "date-time" }
											}
										}
									}
								}
							}
						}
					}
				},
				"tags": ["Authentication"]
			}
		},
		"/v1/account/balance": {
			"get": {
				"operationId": "getBalance",
				"summary": "Check credit balance (0 credits)",
				"description": "Returns remaining credits, credits used today, account tier, and rate limit.",
				"responses": {
					"200": {
						"description": "Account balance",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "object",
											"properties": {
												"credits_remaining": { "type": "integer" },
												"credits_used_today": { "type": "integer" },
												"tier": { "type": "string" },
												"rate_limit": { "type": "integer" }
											}
										},
										"meta": { "$ref": "#/components/schemas/Meta" }
									}
								}
							}
						}
					}
				},
				"tags": ["Account"]
			}
		},
		"/v1/account/usage": {
			"get": {
				"operationId": "getUsage",
				"summary": "Usage statistics (0 credits)",
				"description": "Returns usage stats with by_endpoint and by_day breakdown, success rate, and average latency.",
				"parameters": [
					{ "$ref": "#/components/parameters/days" },
					{ "name": "key_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by API key ID" }
				],
				"responses": {
					"200": { "description": "Usage statistics" }
				},
				"tags": ["Account"]
			}
		},
		"/health": {
			"get": {
				"operationId": "healthCheck",
				"summary": "System health check (no auth required)",
				"security": [],
				"responses": {
					"200": { "description": "System status" }
				},
				"tags": ["System"]
			}
		},
		"/v1/sources": {
			"get": {
				"operationId": "listSources",
				"summary": "List supported platforms (no auth required)",
				"security": [],
				"responses": {
					"200": { "description": "List of supported platforms and their status" }
				},
				"tags": ["System"]
			}
		},
		"/v1/posts": {
			"get": {
				"operationId": "searchPosts",
				"summary": "Search posts (2 credits)",
				"description": "Search social media posts across platforms with various filters.",
				"parameters": [
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "profile_name", "in": "query", "schema": { "type": "string" }, "description": "Filter by profile username" },
					{ "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Search keyword in post content" },
					{ "name": "media_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by media type" },
					{ "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Start date (YYYY-MM-DD)" },
					{ "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "End date (YYYY-MM-DD)" },
					{ "name": "min_likes", "in": "query", "schema": { "type": "integer" }, "description": "Minimum likes count" },
					{ "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["created_at", "likes", "comments"] }, "description": "Sort field" },
					{ "name": "order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] }, "description": "Sort order" },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/cursor" },
					{ "name": "exclude_profiles", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated profile names to exclude from results" },
					{ "name": "exclude_keywords", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated keywords to exclude — posts containing these words are filtered out" }
				],
				"responses": {
					"200": {
						"description": "List of posts",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } },
										"meta": { "$ref": "#/components/schemas/Meta" },
										"pagination": { "$ref": "#/components/schemas/Pagination" }
									}
								}
							}
						}
					}
				},
				"tags": ["Posts"]
			}
		},
		"/v1/posts/{id}": {
			"get": {
				"operationId": "getPost",
				"summary": "Get single post (1 credit)",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
				],
				"responses": {
					"200": {
						"description": "Post details",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": { "$ref": "#/components/schemas/Post" },
										"meta": { "$ref": "#/components/schemas/Meta" }
									}
								}
							}
						}
					}
				},
				"tags": ["Posts"]
			}
		},
		"/v1/posts/{id}/comments": {
			"get": {
				"operationId": "getPostComments",
				"summary": "Get comments on a post (2 credits)",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/cursor" }
				],
				"responses": {
					"200": { "description": "List of comments on the post" }
				},
				"tags": ["Posts"]
			}
		},
		"/v1/comments": {
			"get": {
				"operationId": "searchComments",
				"summary": "Search comments (2 credits)",
				"description": "Search comments across platforms with filters.",
				"parameters": [
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "profile_name", "in": "query", "schema": { "type": "string" }, "description": "Comment author" },
					{ "name": "post_owner", "in": "query", "schema": { "type": "string" }, "description": "Owner of the post" },
					{ "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Search keyword" },
					{ "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } },
					{ "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/cursor" },
					{ "name": "exclude_profiles", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated profile names to exclude from results" },
					{ "name": "exclude_keywords", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated keywords to exclude — comments containing these words are filtered out" }
				],
				"responses": {
					"200": {
						"description": "List of comments",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } },
										"meta": { "$ref": "#/components/schemas/Meta" },
										"pagination": { "$ref": "#/components/schemas/Pagination" }
									}
								}
							}
						}
					}
				},
				"tags": ["Comments"]
			}
		},
		"/v1/comments/{id}": {
			"get": {
				"operationId": "getComment",
				"summary": "Get single comment (1 credit)",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
				],
				"responses": {
					"200": { "description": "Comment details" }
				},
				"tags": ["Comments"]
			}
		},
		"/v1/profiles": {
			"get": {
				"operationId": "listProfiles",
				"summary": "Browse profiles (2 credits)",
				"description": "Browse and search social media profiles.",
				"parameters": [
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by username or display name" },
					{ "name": "is_verified", "in": "query", "schema": { "type": "boolean" }, "description": "Filter verified profiles" },
					{ "name": "min_followers", "in": "query", "schema": { "type": "integer" }, "description": "Minimum follower count" },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/cursor" }
				],
				"responses": {
					"200": {
						"description": "List of profiles",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } },
										"meta": { "$ref": "#/components/schemas/Meta" },
										"pagination": { "$ref": "#/components/schemas/Pagination" }
									}
								}
							}
						}
					}
				},
				"tags": ["Profiles"]
			}
		},
		"/v1/profiles/{platform}/{name}": {
			"get": {
				"operationId": "getProfile",
				"summary": "Get profile details (1 credit)",
				"description": "Get detailed profile information. Auto-triggers a crawl if the profile is not yet in the database.",
				"parameters": [
					{ "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": ["x", "instagram", "tiktok", "facebook", "linkedin", "youtube"] } },
					{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Profile username" }
				],
				"responses": {
					"200": {
						"description": "Profile details",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": { "$ref": "#/components/schemas/Profile" },
										"meta": { "$ref": "#/components/schemas/Meta" }
									}
								}
							}
						}
					}
				},
				"tags": ["Profiles"]
			}
		},
		"/v1/profiles/{platform}/{name}/posts": {
			"get": {
				"operationId": "getProfilePosts",
				"summary": "Get profile's posts (2 credits)",
				"parameters": [
					{ "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } },
					{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/cursor" }
				],
				"responses": {
					"200": { "description": "Profile's posts" }
				},
				"tags": ["Profiles"]
			}
		},
		"/v1/profiles/{platform}/{name}/comments-received": {
			"get": {
				"operationId": "getProfileCommentsReceived",
				"summary": "Comments on profile's posts (2 credits)",
				"parameters": [
					{ "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } },
					{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/cursor" }
				],
				"responses": {
					"200": { "description": "Comments received on profile's posts" }
				},
				"tags": ["Profiles"]
			}
		},
		"/v1/profiles/{platform}/{name}/interactions": {
			"get": {
				"operationId": "getProfileInteractions",
				"summary": "Profile interaction graph (2 credits)",
				"parameters": [
					{ "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } },
					{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }
				],
				"responses": {
					"200": { "description": "Interaction graph edges" }
				},
				"tags": ["Profiles"]
			}
		},
		"/v1/profiles/{platform}/{name}/stats": {
			"get": {
				"operationId": "getProfileStats",
				"summary": "Profile engagement stats (5 credits)",
				"parameters": [
					{ "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } },
					{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } },
					{ "$ref": "#/components/parameters/days" }
				],
				"responses": {
					"200": { "description": "Engagement statistics" }
				},
				"tags": ["Profiles"]
			}
		},
		"/v1/analytics/trending": {
			"get": {
				"operationId": "getTrending",
				"summary": "Trending posts and profiles (5 credits)",
				"description": "Get top posts and profiles by engagement within a time window. Optionally filter by keyword to get trending content about a specific topic.",
				"parameters": [
					{ "$ref": "#/components/parameters/days" },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Optional keyword to filter trending content by topic" },
					{ "name": "exclude_profiles", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated profile names to exclude" },
					{ "name": "exclude_keywords", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated keywords to exclude" }
				],
				"responses": {
					"200": { "description": "Trending posts and profiles" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/sentiment": {
			"get": {
				"operationId": "analyzeSentiment",
				"summary": "Sentiment analysis (5 credits)",
				"description": "Analyze sentiment for a keyword or topic. Returns positive, negative, and neutral counts with sample posts.",
				"parameters": [
					{ "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Keyword or topic to analyze" },
					{ "$ref": "#/components/parameters/days" },
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "exclude_profiles", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated profile names to exclude" },
					{ "name": "exclude_keywords", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated keywords to exclude" }
				],
				"responses": {
					"200": {
						"description": "Sentiment breakdown",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": { "$ref": "#/components/schemas/SentimentResult" },
										"meta": { "$ref": "#/components/schemas/Meta" }
									}
								}
							}
						}
					}
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/engagement-ranking": {
			"get": {
				"operationId": "getEngagementRanking",
				"summary": "Profiles ranked by engagement (5 credits)",
				"description": "Rank profiles by total engagement. Optionally filter by keyword to rank engagement on posts about a specific topic.",
				"parameters": [
					{ "$ref": "#/components/parameters/platform" },
					{ "$ref": "#/components/parameters/days" },
					{ "$ref": "#/components/parameters/limit" },
					{ "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Optional keyword to filter by topic" },
					{ "name": "exclude_profiles", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated profile names to exclude" },
					{ "name": "exclude_keywords", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated keywords to exclude" }
				],
				"responses": {
					"200": { "description": "Profiles ranked by engagement" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/topics": {
			"get": {
				"operationId": "getTopics",
				"summary": "Trending topics and hashtags (5 credits)",
				"description": "Discover topics being discussed using semantic clustering. Optionally filter by keyword to narrow clustering to posts about a specific subject.",
				"parameters": [
					{ "$ref": "#/components/parameters/days" },
					{ "$ref": "#/components/parameters/platform" },
					{ "$ref": "#/components/parameters/limit" },
					{ "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Optional keyword to filter posts before clustering" },
					{ "name": "exclude_profiles", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated profile names to exclude" },
					{ "name": "exclude_keywords", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated keywords to exclude" }
				],
				"responses": {
					"200": { "description": "Topic summaries from hashtags" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/compare": {
			"get": {
				"operationId": "compareProfiles",
				"summary": "Compare profiles side-by-side (5 credits)",
				"description": "Compare two or more profiles across platforms.",
				"parameters": [
					{ "name": "profiles", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated list of platform:username pairs (e.g. x:user1,x:user2)" }
				],
				"responses": {
					"200": { "description": "Profile comparison data" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/experts": {
			"get": {
				"operationId": "findExperts",
				"summary": "Find topic experts (5 credits)",
				"description": "Find profiles that frequently post about a specific topic, ranked by authority (post frequency × relevance × engagement).",
				"parameters": [
					{ "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Topic to search for (e.g. saham, politik, AI)" },
					{ "$ref": "#/components/parameters/days" },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "exclude_profiles", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated profile names to exclude" },
					{ "name": "exclude_keywords", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated keywords to exclude" }
				],
				"responses": {
					"200": { "description": "Expert profiles ranked by authority score" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/sentiment-trend": {
			"get": {
				"operationId": "sentimentTrend",
				"summary": "Sentiment trend over time (3 credits)",
				"description": "Get daily sentiment breakdown (positive/negative/neutral counts). When keyword is provided, uses semantic search to find topic-relevant posts and computes sentiment from those.",
				"parameters": [
					{ "$ref": "#/components/parameters/days" },
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Optional topic to filter by using semantic search" }
				],
				"responses": {
					"200": { "description": "Daily sentiment counts" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/hashtags": {
			"get": {
				"operationId": "hashtagTrending",
				"summary": "Trending hashtags (3 credits)",
				"description": "Get trending hashtags ranked by engagement. When keyword is provided, shows hashtags used in topic-relevant posts via semantic search.",
				"parameters": [
					{ "$ref": "#/components/parameters/days" },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Optional topic to filter by using semantic search" }
				],
				"responses": {
					"200": { "description": "Hashtags ranked by engagement" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/mentions": {
			"get": {
				"operationId": "mentionRanking",
				"summary": "Most-mentioned profiles (3 credits)",
				"description": "Get most-mentioned profiles ranked by mention count and engagement. When keyword is provided, shows who is mentioned in topic-relevant posts via semantic search.",
				"parameters": [
					{ "$ref": "#/components/parameters/days" },
					{ "$ref": "#/components/parameters/limit" },
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Optional topic to filter by using semantic search" }
				],
				"responses": {
					"200": { "description": "Profiles ranked by mention count" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/best-time": {
			"get": {
				"operationId": "bestTime",
				"summary": "Best posting times (3 credits)",
				"description": "Get the best time to post based on engagement patterns. Returns hour × day-of-week heatmap. When keyword is provided, analyzes posting times of topic-relevant posts via semantic search.",
				"parameters": [
					{ "$ref": "#/components/parameters/platform" },
					{ "name": "profile_name", "in": "query", "schema": { "type": "string" }, "description": "Filter by profile name" },
					{ "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Optional topic to analyze posting times for" },
					{ "$ref": "#/components/parameters/days" }
				],
				"responses": {
					"200": { "description": "Time slots ranked by average engagement" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/analytics/growth": {
			"get": {
				"operationId": "growth",
				"summary": "Follower growth (3 credits)",
				"description": "Get follower/following growth over time for a specific profile from daily snapshots. Filtering via exclude_profiles/exclude_keywords is not supported.",
				"parameters": [
					{ "name": "platform", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Platform" },
					{ "name": "profile_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Profile username" },
					{ "$ref": "#/components/parameters/days" }
				],
				"responses": {
					"200": { "description": "Daily follower snapshots" }
				},
				"tags": ["Analytics"]
			}
		},
		"/v1/search": {
			"post": {
				"operationId": "semanticSearch",
				"summary": "Semantic search (5 credits)",
				"description": "AI-powered semantic search across millions of posts and articles.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["query"],
								"properties": {
									"query": { "type": "string", "description": "Natural language search query" },
									"limit": { "type": "integer", "default": 20, "maximum": 100 },
									"filters": {
										"type": "object",
										"properties": {
											"platforms": { "type": "array", "items": { "type": "string" } },
											"date_from": { "type": "string", "format": "date" },
											"date_to": { "type": "string", "format": "date" },
											"exclude_profiles": { "type": "array", "items": { "type": "string" }, "description": "Profile names to exclude from results" },
											"exclude_keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords to exclude — posts containing these words are filtered out" }
										}
									}
								}
							}
						}
					}
				},
				"responses": {
					"200": { "description": "Semantic search results" }
				},
				"tags": ["Search"]
			}
		},
		"/v1/search/similar/{id}": {
			"get": {
				"operationId": "findSimilar",
				"summary": "Find similar posts (5 credits)",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
				],
				"responses": {
					"200": { "description": "Similar posts" }
				},
				"tags": ["Search"]
			}
		},
		"/v1/seeds": {
			"get": {
				"operationId": "listSeeds",
				"summary": "List monitored profiles (0 credits)",
				"responses": {
					"200": { "description": "List of active seed profiles being monitored" }
				},
				"tags": ["Seeds & Crawl"]
			},
			"post": {
				"operationId": "addSeed",
				"summary": "Add seed profile (0 credits)",
				"description": "Add a profile to be monitored and crawled. Returns 409 if already monitoring. Re-adding a previously deleted seed reactivates it with the same ID.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["platform", "profile_id"],
								"properties": {
									"platform": { "type": "string", "enum": ["x", "instagram", "tiktok", "facebook", "linkedin", "youtube", "news_portal"] },
									"profile_id": { "type": "string", "description": "Profile username" },
									"label": { "type": "string" },
									"post_limit": { "type": "integer", "default": 50 },
									"comment_limit": { "type": "integer", "default": 100 },
									"schedule_enabled": { "type": "boolean", "default": false },
									"schedule_interval_minutes": { "type": "integer", "default": 1440 }
								}
							}
						}
					}
				},
				"responses": {
					"201": { "description": "Seed created or reactivated" },
					"409": { "description": "Already monitoring this profile" }
				},
				"tags": ["Seeds & Crawl"]
			}
		},
		"/v1/seeds/{id}": {
			"delete": {
				"operationId": "deleteSeed",
				"summary": "Stop monitoring a profile (0 credits)",
				"description": "Soft delete — deactivates the seed. Crawled data is preserved. Re-adding the same profile reactivates it.",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
				],
				"responses": {
					"204": { "description": "Seed deactivated" }
				},
				"tags": ["Seeds & Crawl"]
			}
		},
		"/v1/seeds/{id}/crawl": {
			"post": {
				"operationId": "triggerCrawl",
				"summary": "Trigger immediate crawl (10 credits)",
				"description": "Returns job status with queue position and estimated wait time. Returns 409 if a crawl is already pending or running for this profile.",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
				],
				"responses": {
					"202": { "description": "Crawl scheduled with queue position and estimated wait" },
					"409": { "description": "A crawl is already pending or running for this profile" }
				},
				"tags": ["Seeds & Crawl"]
			}
		},
		"/v1/seeds/{id}/jobs": {
			"get": {
				"operationId": "getCrawlJobs",
				"summary": "Crawl history (1 credit)",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
				],
				"responses": {
					"200": { "description": "Crawl job history with status and human-readable messages" }
				},
				"tags": ["Seeds & Crawl"]
			}
		},
		"/v1/export": {
			"post": {
				"operationId": "startExport",
				"summary": "Start export job (0 credits)",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["type", "format"],
								"properties": {
									"type": { "type": "string", "enum": ["posts", "comments", "profiles"] },
									"format": { "type": "string", "enum": ["csv", "json"] },
									"filters": { "type": "object" }
								}
							}
						}
					}
				},
				"responses": {
					"202": { "description": "Export job started" }
				},
				"tags": ["Export"]
			}
		},
		"/v1/export/{jobId}": {
			"get": {
				"operationId": "getExportStatus",
				"summary": "Check export status (0 credits)",
				"parameters": [
					{ "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }
				],
				"responses": {
					"200": { "description": "Export status and download URL when ready" }
				},
				"tags": ["Export"]
			}
		},
		"/v1/recommendations/{name}": {
			"get": {
				"operationId": "getRecommendations",
				"summary": "AI-generated recommendations (15 credits)",
				"description": "Generate AI-powered recommendations derived from social media buzz. Available types: products, movies, books, software, games, travel, skills, content, marketing, problems.",
				"parameters": [
					{ "name": "name", "in": "path", "required": true, "schema": { "type": "string", "enum": ["products", "movies", "books", "software", "games", "travel", "skills", "content", "marketing", "problems"] }, "description": "Recommendation type" },
					{ "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Topic to generate recommendations for" },
					{ "$ref": "#/components/parameters/days" },
					{ "$ref": "#/components/parameters/platform" }
				],
				"responses": {
					"200": { "description": "AI-generated recommendations based on social data" }
				},
				"tags": ["Recommendations"]
			}
		},
		"/v1/conversations": {
			"get": {
				"operationId": "listConversations",
				"summary": "List chat conversations (0 credits)",
				"description": "List all chat conversations for the authenticated user, newest first.",
				"parameters": [
					{ "$ref": "#/components/parameters/limit" },
					{ "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of conversations to skip" }
				],
				"responses": {
					"200": { "description": "List of conversations with titles and timestamps" }
				},
				"tags": ["Conversations"]
			}
		},
		"/v1/conversations/{id}": {
			"get": {
				"operationId": "getConversation",
				"summary": "Get conversation with messages (0 credits)",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
				],
				"responses": {
					"200": { "description": "Conversation with all messages" }
				},
				"tags": ["Conversations"]
			},
			"patch": {
				"operationId": "renameConversation",
				"summary": "Rename conversation (0 credits)",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["title"],
								"properties": {
									"title": { "type": "string", "description": "New conversation title" }
								}
							}
						}
					}
				},
				"responses": {
					"200": { "description": "Conversation renamed" }
				},
				"tags": ["Conversations"]
			},
			"delete": {
				"operationId": "deleteConversation",
				"summary": "Delete conversation (0 credits)",
				"parameters": [
					{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
				],
				"responses": {
					"204": { "description": "Conversation deleted" }
				},
				"tags": ["Conversations"]
			}
		},
		"/v1/chat": {
			"post": {
				"operationId": "aiChat",
				"summary": "AI chat with tool-use (20 credits)",
				"description": "AI-powered chat that can use Verosight tools to answer questions about social media data. Returns Server-Sent Events (SSE). Supports persistent conversations via conversation_id. Available tools: search_posts, get_trending, get_sentiment, get_topics, get_engagement_ranking, list_posts, get_profile, list_profiles, get_profile_stats, find_experts, recommend_products, recommend_movies, recommend_books, recommend_software, recommend_games, recommend_travel, recommend_skills, recommend_content, recommend_marketing, recommend_problems.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": ["message"],
								"properties": {
									"message": { "type": "string", "description": "User message" },
									"conversation_id": { "type": "string", "format": "uuid", "description": "Optional conversation ID to continue an existing conversation. Omit to start a new one." }
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Server-Sent Events stream",
						"content": { "text/event-stream": {} }
					}
				},
				"tags": ["AI"]
			}
		},
		"/v1/mcp/sse": {
			"get": {
				"operationId": "mcpSse",
				"summary": "MCP Server (SSE transport)",
				"description": "Model Context Protocol server endpoint for AI assistants (Claude, Cursor, Windsurf). Connect via SSE with your API key in the X-API-Key header. Provides 13 tools: search_posts, get_post, search_comments, list_profiles, get_profile, get_profile_stats, get_trending, analyze_sentiment, get_topics, compare_profiles, find_experts, semantic_search, get_balance.",
				"security": [{ "apiKey": [] }],
				"responses": {
					"200": {
						"description": "SSE stream for MCP communication",
						"content": { "text/event-stream": {} }
					}
				},
				"tags": ["MCP"]
			}
		}
	},
	"tags": [
		{ "name": "Authentication", "description": "API key exchange and JWT management" },
		{ "name": "Account", "description": "Credit balance and usage statistics" },
		{ "name": "System", "description": "Health checks and platform information" },
		{ "name": "Posts", "description": "Search and retrieve social media posts" },
		{ "name": "Comments", "description": "Search and retrieve comments" },
		{ "name": "Profiles", "description": "Browse and analyze social media profiles" },
		{ "name": "Analytics", "description": "Trending, sentiment, topics, and comparisons" },
		{ "name": "Recommendations", "description": "AI-generated recommendations from social media buzz" },
		{ "name": "Search", "description": "AI-powered semantic search" },
		{ "name": "Seeds & Crawl", "description": "Manage monitored profiles and trigger crawls" },
		{ "name": "Export", "description": "Export data in CSV or JSON format" },
		{ "name": "Conversations", "description": "Manage AI chat conversation history" },
		{ "name": "AI", "description": "AI chat with tool-use capabilities" },
		{ "name": "MCP", "description": "Model Context Protocol server for AI assistants" }
	]
}