{"openapi":"3.1.0","info":{"title":"Mentionkit Public API","version":"1.0.0","description":"A simple API for Mentionkit data. This API is meant for developers who want to fetch mentions, projects, keywords, organization usage stats, and update mention review status."},"servers":[{"url":"https://api.mentionkit.com","description":"Production"},{"url":"http://localhost:2000","description":"Local development"}],"tags":[{"name":"Mentions","description":"Read mention feed data and update mention review status."},{"name":"Keywords","description":"Read tracked keywords."},{"name":"Projects","description":"Read organization projects."},{"name":"Organization","description":"Read organization profile, limits, and usage."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"APIKey"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"MentionItem":{"type":"object","properties":{"id":{"type":"integer"},"platform":{"type":"string","enum":["REDDIT","X","LINKEDIN","HN","YOUTUBE","BLUESKY","TIKTOK","MEDIUM","GITHUB","SLACK"]},"keywordValue":{"type":"string"},"projectId":{"type":"integer","nullable":true},"trackerId":{"type":"integer","nullable":true},"subreddit":{"type":"string","nullable":true},"authorHandle":{"type":"string","nullable":true},"text":{"type":"string"},"lang":{"type":"string","nullable":true},"sourceCreatedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"sourceUrl":{"type":"string","nullable":true},"score":{"type":"integer","enum":[0,1],"description":"Mention quality: 1 is high score and 0 is low score."},"reason":{"type":"string","nullable":true},"angle":{"type":"string","nullable":true},"engagement":{"type":"object","nullable":true,"additionalProperties":true},"communityId":{"type":"string","nullable":true},"communityName":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"commentStatus":{"type":"integer","enum":[1,0,-1]},"projectName":{"type":"string","nullable":true},"platformPostId":{"type":"string","nullable":true},"permalink":{"type":"string","nullable":true},"redditPostId":{"type":"string","nullable":true},"redditCommentId":{"type":"string","nullable":true}},"required":["id","platform","keywordValue","projectId","trackerId","subreddit","authorHandle","text","lang","sourceCreatedAt","createdAt","sourceUrl","score","reason","angle","engagement","communityId","communityName","tags","commentStatus","projectName","platformPostId","permalink","redditPostId","redditCommentId"]},"MentionListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MentionItem"}},"nextCursor":{"type":"integer","nullable":true},"limit":{"type":"integer","nullable":true},"sort":{"type":"string","enum":["newest","oldest"]},"project":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true}}}},"required":["items","nextCursor","limit","sort","project"]},"MentionStatusUpdateRequest":{"type":"object","properties":{"commentStatus":{"type":"integer","enum":[1,-1]}},"required":["commentStatus"]},"MentionStatusUpdateResponse":{"type":"object","properties":{"id":{"type":"integer"},"commentStatus":{"type":"integer","enum":[1,-1]},"commentStatusAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","commentStatus","commentStatusAt"]},"ProjectListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true},"siteDomain":{"type":"string","nullable":true},"bizName":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"companyMoat":{"type":"string","nullable":true},"targetCustomer":{"type":"string","nullable":true},"customerProblems":{"type":"string","nullable":true},"conversationGuidance":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"faviconUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"total":{"type":"integer"}},"required":["items","total"]},"KeywordSevenDayPerformanceItem":{"type":"object","properties":{"date":{"type":"string","format":"date"},"totalMentions":{"type":"integer"}},"required":["date","totalMentions"]},"KeywordListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"value":{"type":"string"},"category":{"type":"string","nullable":true},"subprompt":{"type":"string","nullable":true},"mentionCount":{"type":"integer"},"sevenDayPerformance":{"type":"array","description":"Daily mention totals for the latest seven UTC calendar days.","items":{"$ref":"#/components/schemas/KeywordSevenDayPerformanceItem"}},"projectId":{"type":"integer","nullable":true},"platforms":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["REDDIT","X","LINKEDIN","HN","YOUTUBE","BLUESKY","TIKTOK","MEDIUM","GITHUB","SLACK"]},"enabled":{"type":"boolean"}},"required":["platform","enabled"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","value","category","subprompt","mentionCount","sevenDayPerformance","projectId","platforms","createdAt","updatedAt"]}},"total":{"type":"integer"}},"required":["items","total"]},"MeResponse":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"logo":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","slug","createdAt"]},"counts":{"type":"object","properties":{"projects":{"type":"integer"},"keywords":{"type":"integer"},"trackers":{"type":"integer"},"redditKeywords":{"type":"integer"},"xKeywords":{"type":"integer"},"linkedinKeywords":{"type":"integer"},"hnKeywords":{"type":"integer"}},"required":["projects","keywords","trackers","redditKeywords","xKeywords","linkedinKeywords","hnKeywords"]},"limits":{"type":"object","properties":{"projectLimit":{"type":"integer","nullable":true},"reddit":{"type":"integer","nullable":true},"x":{"type":"integer","nullable":true},"linkedin":{"type":"integer","nullable":true},"hn":{"type":"integer","nullable":true},"trackerLimit":{"type":"integer","nullable":true}},"required":["projectLimit","reddit","x","linkedin","hn","trackerLimit"]},"usage":{"type":"object","properties":{"projects":{"type":"object"},"redditKeywords":{"type":"object"},"xKeywords":{"type":"object"},"linkedinKeywords":{"type":"object"},"hnKeywords":{"type":"object"},"trackers":{"type":"object"}},"required":["projects","redditKeywords","xKeywords","linkedinKeywords","hnKeywords","trackers"]}},"required":["organization","counts","limits","usage"]}}},"paths":{"/api/v1/mentions":{"get":{"tags":["Mentions"],"summary":"List mentions","description":"Returns mentions for the organization linked to your API key. Start with this endpoint if you want to build your own mention dashboard.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"sort","description":"Sort order for results.","schema":{"type":"string","enum":["newest","oldest"],"default":"newest"}},{"in":"query","name":"cursor","description":"Use this for pagination (pass the previous nextCursor value).","schema":{"type":"integer"}},{"in":"query","name":"limit","description":"Maximum mentions to return. Values above 250 are capped at 250.","schema":{"type":"integer","minimum":1,"maximum":250}},{"in":"query","name":"projectId","description":"Filter by one project ID.","schema":{"type":"integer"}},{"in":"query","name":"category","description":"Filter by keyword category.","schema":{"type":"string","enum":["BRAND","COMPETITOR","INDUSTRYTERM"]}},{"in":"query","name":"platform","description":"Filter by platform (reddit, x, twitter, linkedin, hn, hackernews, youtube, yt, bluesky, bsky, tiktok, medium, github, or slack).","schema":{"type":"string"}},{"in":"query","name":"score","description":"Comma-separated mention scores. Use 1 for high-score mentions, 0 for low-score mentions, or 0,1 for both. Both scores are returned by default.","schema":{"type":"string"}},{"in":"query","name":"keywords","description":"Comma-separated keywords, e.g. mentionkit,social listening.","schema":{"type":"string"}},{"in":"query","name":"tags","description":"Comma-separated mention tags (any-match), e.g. insight,alternatives. Allowed: positive, negative, comparing, alternatives, promotional, insight, ai-slop.","schema":{"type":"string"}},{"in":"query","name":"startdate","description":"Start date (inclusive) in YYYY-MM-DD format. Filters by sourceCreatedAt.","schema":{"type":"string"}},{"in":"query","name":"enddate","description":"End date (inclusive) in YYYY-MM-DD format. Filters by sourceCreatedAt.","schema":{"type":"string"}}],"responses":{"200":{"description":"Mentions fetched successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MentionListResponse"},"example":{"items":[{"id":2001,"platform":"REDDIT","keywordValue":"example alternative","projectId":3001,"trackerId":null,"subreddit":"saas","authorHandle":"user_123","text":"Looking for alternatives to ExampleMonitor for social listening.","lang":"en","sourceCreatedAt":"2026-03-20T10:15:00.000Z","createdAt":"2026-03-20T10:15:02.000Z","sourceUrl":"https://www.reddit.com/r/saas/comments/p_abc123/","score":1,"reason":"User wants alternatives to their current monitoring tool.","angle":"Acknowledge the switching pain and explain the relevant workflow.","engagement":{"likes":4,"comments":2},"communityId":null,"communityName":null,"tags":["alternatives"],"commentStatus":1,"projectName":"Example Project","platformPostId":"p_abc123","permalink":"https://www.reddit.com/r/saas/comments/p_abc123/","redditPostId":"rp_abc123","redditCommentId":"rc_def456"}],"nextCursor":null,"limit":50,"sort":"newest","project":null}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid API key"}}}},"403":{"description":"API access blocked. The organization is deactivated for API usage and must have an active trial, active paid subscription, or billing exemption.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"API access requires a trial, paid subscription, or billing exemption"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/mentions/{id}":{"post":{"tags":["Mentions"],"summary":"Update mention status","description":"Sets a mention review status. Use commentStatus=1 to approve and commentStatus=-1 to decline.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"description":"Mention ID.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MentionStatusUpdateRequest"},"example":{"commentStatus":1}}}},"responses":{"200":{"description":"Mention status updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MentionStatusUpdateResponse"},"example":{"id":2001,"commentStatus":1,"commentStatusAt":"2026-03-24T02:00:00.000Z"}}}},"400":{"description":"Invalid mention ID or invalid commentStatus value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"commentStatus must be 1 or -1"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid API key"}}}},"403":{"description":"API access blocked. The organization is deactivated for API usage and must have an active trial, active paid subscription, or billing exemption.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"API access requires a trial, paid subscription, or billing exemption"}}}},"404":{"description":"Mention not found for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Mention not found"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/keywords":{"get":{"tags":["Keywords"],"summary":"List keywords","description":"Returns active keywords for your organization with all-time mention counts and daily totals for the latest seven UTC calendar days. Soft-deleted keywords are excluded.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Keywords fetched successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordListResponse"},"example":{"items":[{"id":4001,"value":"example alternative","category":"BRAND","subprompt":null,"mentionCount":4,"sevenDayPerformance":[{"date":"2026-03-18","totalMentions":0},{"date":"2026-03-19","totalMentions":1},{"date":"2026-03-20","totalMentions":0},{"date":"2026-03-21","totalMentions":1},{"date":"2026-03-22","totalMentions":0},{"date":"2026-03-23","totalMentions":1},{"date":"2026-03-24","totalMentions":1}],"projectId":3001,"createdAt":"2026-03-24T01:35:50.247Z","updatedAt":"2026-03-24T01:45:03.878Z","platforms":[{"platform":"REDDIT","enabled":true}]}],"total":2}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API access blocked. The organization is deactivated for API usage and must have an active trial, active paid subscription, or billing exemption.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"API access requires a trial, paid subscription, or billing exemption"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/projects":{"get":{"tags":["Projects"],"summary":"List projects","description":"Returns projects for your organization. Use this to let users pick a project before you apply your own filtering in your app.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Projects fetched successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectListResponse"},"example":{"items":[{"id":3001,"name":"Example Project","siteDomain":"example.com","bizName":"ExampleCo","description":"ExampleCo helps teams monitor social mentions and respond faster.","companyMoat":"- Faster setup\n- Clearer alerts","targetCustomer":"- Small marketing teams\n- Agency owners","customerProblems":"- Important posts get missed\n- Manual monitoring takes too long","conversationGuidance":"## Lead generation\n- People asking for a social monitoring tool","type":"ECOM","faviconUrl":"https://example.com/favicon.ico","createdAt":"2026-03-21T00:26:05.651Z","updatedAt":"2026-03-24T01:29:08.985Z"}],"total":1}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API access blocked. The organization is deactivated for API usage and must have an active trial, active paid subscription, or billing exemption.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"API access requires a trial, paid subscription, or billing exemption"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/me":{"get":{"tags":["Organization"],"summary":"Get organization usage overview","description":"Returns one summary object with organization details, usage counts, and plan limits. This endpoint is useful for showing plan usage cards in your frontend.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Organization summary fetched successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"},"example":{"organization":{"id":"org_123","name":"Example Organization","slug":"example-org","logo":null,"createdAt":"2026-03-21T00:26:01.515Z"},"counts":{"projects":1,"keywords":2,"trackers":0,"redditKeywords":2,"xKeywords":0,"linkedinKeywords":0,"hnKeywords":0},"limits":{"projectLimit":2,"reddit":10,"x":3,"linkedin":1,"hn":10,"trackerLimit":2},"usage":{"projects":{"used":1,"limit":2,"remaining":1},"redditKeywords":{"used":2,"limit":10,"remaining":8},"xKeywords":{"used":0,"limit":3,"remaining":3},"linkedinKeywords":{"used":0,"limit":1,"remaining":1},"hnKeywords":{"used":0,"limit":10,"remaining":10},"trackers":{"used":0,"limit":2,"remaining":2}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API access blocked. The organization is deactivated for API usage and must have an active trial, active paid subscription, or billing exemption.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"API access requires a trial, paid subscription, or billing exemption"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}