{"openapi":"3.1.0","info":{"title":"RedditFind Open API","version":"1.0.0","description":"Public REST API for Community Discovery, Community Overview, Post Monitoring, usage inspection, and access management for RedditFind integrations."},"servers":[{"url":"https://redditfind.ai"}],"tags":[{"name":"Community Discovery","description":"Queue, inspect, and retrieve Community Discovery jobs that turn product context into subreddit shortlists."},{"name":"Community Overview","description":"Queue, inspect, and retrieve Subreddit analysis jobs for rules, content patterns, and participation guidance."},{"name":"Post Monitoring","description":"Create and manage recurring monitoring jobs, then read recent hits and execution status."},{"name":"Usage","description":"Read account-level usage, credit balance, and resource summaries for the current token."},{"name":"Access & Auth","description":"Inspect the current token identity, manage API keys, and rotate or revoke active credentials."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}}},"paths":{"/api/open/v1/keys":{"get":{"summary":"List API keys","description":"List API keys that belong to the current account and inspect their environment, scopes, and recent usage.","tags":["Access & Auth"],"operationId":"listApiKeys","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}},"post":{"summary":"Create an API key","description":"Create a new API key for the current account and return the raw token once.","tags":["Access & Auth"],"operationId":"createApiKey","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"default":{"value":{"name":"Integration key","environment":"test","scopes":["access:read","community_discovery:write"]}}}}}},"responses":{"201":{"description":"API key created.","content":{"application/json":{"examples":{"default":{"value":{"id":"key_123","name":"Integration key","environment":"test","scopes":["access:read","community_discovery:write"],"maskedToken":"rf_test_************************abcd","rawToken":"rf_test_example_secret"}}}}}}}}},"/api/open/v1/keys/{key_id}/rotate":{"post":{"summary":"Rotate an API key","description":"Rotate a specific API key and return the new raw token once.","tags":["Access & Auth"],"operationId":"rotateApiKey","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/keys/{key_id}/revoke":{"post":{"summary":"Revoke an API key","description":"Revoke a specific API key and invalidate it immediately.","tags":["Access & Auth"],"operationId":"revokeApiKey","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/community-discovery/jobs":{"post":{"summary":"Create a Community Discovery job","description":"Queue an async Community Discovery run that turns product, audience, and scenario context into a ranked subreddit shortlist.","tags":["Community Discovery"],"operationId":"createCommunityDiscoveryJob","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"default":{"value":{"product_summary":"A user research tool for indie makers and SaaS teams.","target_audience":"Indie makers, SaaS founders, and growth teams","use_cases":["Product validation","Community-led growth"],"constraints":["Prefer active English-speaking communities"],"language":"en"}}}}}},"responses":{"201":{"description":"Community Discovery job created.","content":{"application/json":{"examples":{"default":{"value":{"id":"cdj_123","object":"community_discovery.job","status":"queued","progress":0,"stage_message":"Queued","result_id":null,"created_at":"2026-03-26T09:00:00.000Z","updated_at":"2026-03-26T09:00:00.000Z","reused":false}}}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"examples":{"default":{"value":{"error":{"code":"INVALID_ARGUMENT","message":"Request body is invalid","request_id":"req_123"}}}}}}}}},"get":{"summary":"List Community Discovery jobs","description":"List Community Discovery jobs that belong to the current account.","tags":["Community Discovery"],"operationId":"listCommunityDiscoveryJobs","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/community-discovery/jobs/{job_id}":{"get":{"summary":"Get Community Discovery job status","description":"Read the current state, progress, and result linkage for a Community Discovery job.","tags":["Community Discovery"],"operationId":"getCommunityDiscoveryJob","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}},"delete":{"summary":"Delete a Community Discovery job","description":"Cancel or delete a Community Discovery job that belongs to the current account.","tags":["Community Discovery"],"operationId":"deleteCommunityDiscoveryJob","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/community-discovery/jobs/{job_id}/result":{"get":{"summary":"Get Community Discovery result","description":"Read the final Community Discovery result payload for a completed job.","tags":["Community Discovery"],"operationId":"getCommunityDiscoveryResult","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Completed Community Discovery result.","content":{"application/json":{"examples":{"default":{"value":{"id":"cdr_123","object":"community_discovery.result","job_id":"cdj_123","strategy_text":"Prioritize builder and SaaS operator communities with recurring validation and acquisition discussion.","notes":"Focus on communities that combine clear pain-point language with enough weekly activity to support follow-up monitoring.","queries":["product validation reddit","saas founder reddit"],"clusters":[{"label":"Builder core","communities":["r/saas","r/micro_saas"]}],"created_at":"2026-03-26T09:03:00.000Z"}}}}}},"409":{"description":"Result not ready yet.","content":{"application/json":{"examples":{"default":{"value":{"error":{"code":"RESULT_NOT_READY","message":"The result is not ready yet","request_id":"req_123"}}}}}}}}}},"/api/open/v1/community-overview/jobs":{"post":{"summary":"Create a Community Overview job","description":"Queue an async Subreddit analysis run for rules, patterns, and participation guidance.","tags":["Community Overview"],"operationId":"createCommunityOverviewJob","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"default":{"value":{"subreddit":"ChatGPTCoding","include_about":true,"include_rules":true,"hot_limit":10,"new_limit":10,"language":"en"}}}}}},"responses":{"201":{"description":"Community Overview job created.","content":{"application/json":{"examples":{"default":{"value":{"id":"covj_123","object":"community_overview.job","subreddit":"ChatGPTCoding","status":"queued","progress":0,"stage_message":"Queued","result_id":null,"created_at":"2026-03-26T09:00:00.000Z","updated_at":"2026-03-26T09:00:00.000Z","reused":false}}}}}}}},"get":{"summary":"List Community Overview jobs","description":"List Community Overview jobs that belong to the current account.","tags":["Community Overview"],"operationId":"listCommunityOverviewJobs","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/community-overview/jobs/{job_id}":{"get":{"summary":"Get Community Overview job status","description":"Read the current state, progress, and result linkage for a Community Overview job.","tags":["Community Overview"],"operationId":"getCommunityOverviewJob","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}},"delete":{"summary":"Delete a Community Overview job","description":"Delete a Community Overview job or its associated stored analysis for the current account.","tags":["Community Overview"],"operationId":"deleteCommunityOverviewJob","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/community-overview/jobs/{job_id}/result":{"get":{"summary":"Get Community Overview result","description":"Read the final Subreddit analysis result for a completed Community Overview job.","tags":["Community Overview"],"operationId":"getCommunityOverviewResult","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Completed Community Overview result.","content":{"application/json":{"examples":{"default":{"value":{"id":"covr_123","object":"community_overview.result","job_id":"covj_123","subreddit":"ChatGPTCoding","model":"gpt-4.1","overview":{"about":{"name":"ChatGPTCoding","title":"ChatGPT Coding"},"rules":{"rules":[{"short_name":"Be civil"}]}},"analysis":{"summary":"A serious builder community that rewards evidence, technical specificity, and practical workflow detail."},"created_at":"2026-03-26T09:03:00.000Z","cached_at":"2026-03-26T09:03:00.000Z"}}}}}},"409":{"description":"Result not ready yet.","content":{"application/json":{"examples":{"default":{"value":{"error":{"code":"RESULT_NOT_READY","message":"The result is not ready yet","request_id":"req_123"}}}}}}}}}},"/api/open/v1/monitoring/jobs":{"post":{"summary":"Create a monitoring job","description":"Create a recurring monitoring workflow for a subreddit or search query.","tags":["Post Monitoring"],"operationId":"createMonitoringJob","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"default":{"value":{"mode":"search","query":"cursor OR copilot","search_subreddits":["ChatGPTCoding"],"search_sort":"new","search_time":"week","limit":20,"frequency_minutes":60,"include_comments":false,"language":"en"}}}}}},"responses":{"201":{"description":"Monitoring job created.","content":{"application/json":{"examples":{"default":{"value":{"id":"mon_123","object":"monitoring.job","mode":"search","subreddit":"","query":"cursor OR copilot","search_subreddits":["ChatGPTCoding"],"search_restrict_sr":true,"search_sort":"new","search_time":"week","sort_type":"hot","limit":20,"frequency_minutes":60,"is_active":true,"include_comments":false,"comment_sort":"best","comment_limit":10,"comment_depth":2,"auto_analyze":true,"last_run_at":null,"next_run_at":"2026-03-26T10:00:00.000Z","created_at":"2026-03-26T09:00:00.000Z","updated_at":"2026-03-26T09:00:00.000Z"}}}}}}}},"get":{"summary":"List monitoring jobs","description":"List monitoring jobs that belong to the current account.","tags":["Post Monitoring"],"operationId":"listMonitoringJobs","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/monitoring/jobs/{job_id}":{"get":{"summary":"Get monitoring job status","description":"Read a monitoring job together with its recent execution history.","tags":["Post Monitoring"],"operationId":"getMonitoringJob","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}},"patch":{"summary":"Update monitoring job state","description":"Enable or disable an existing monitoring job without recreating it.","tags":["Post Monitoring"],"operationId":"updateMonitoringJob","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"default":{"value":{"is_active":false}}}}}},"responses":{"200":{"description":"Successful response."}}},"delete":{"summary":"Delete a monitoring job","description":"Delete a monitoring job and stop future scheduling.","tags":["Post Monitoring"],"operationId":"deleteMonitoringJob","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/monitoring/jobs/{job_id}/hits":{"get":{"summary":"List monitoring hits","description":"Read recent hit threads and attached analysis for a monitoring job.","tags":["Post Monitoring"],"operationId":"listMonitoringHits","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Recent monitoring hits.","content":{"application/json":{"examples":{"default":{"value":{"object":"list","data":[{"id":"hit_123","object":"monitoring.hit","title":"Cursor vs Copilot","subreddit":"ChatGPTCoding","author":"builder_1","url":"https://reddit.com/r/ChatGPTCoding/comments/abc123","upvotes":42,"comments_count":18,"created_at":"2026-03-26T09:02:00.000Z","reddit_created_at":"2026-03-26T08:58:00.000Z","analysis":{"pain_point":"Need more controllable AI coding workflow","reply_priority":"high","reply_angle":"Share a repeatable prompt-and-review workflow","suggested_reply_content":"One useful pattern is to force diff-only edits plus a short rationale.","suggested_reply_content_zh":null}}],"has_more":false}}}}}}}}},"/api/open/v1/usage":{"get":{"summary":"Get usage summary","description":"Read credit balance, resource counts, and usage summary for the current token.","tags":["Usage"],"operationId":"getUsageSummary","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/whoami":{"get":{"summary":"Get current token identity","description":"Read the current bearer token identity together with API key and scope summary.","tags":["Access & Auth"],"operationId":"getCurrentTokenIdentity","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Current token identity.","content":{"application/json":{"examples":{"default":{"value":{"object":"open_api.identity","user_id":"user_123","api_key":{"id":"key_123","name":"Integration key","environment":"test","scopes":["access:read","community_discovery:write"]}}}}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"examples":{"default":{"value":{"error":{"code":"UNAUTHORIZED","message":"Missing or invalid bearer token","request_id":"req_123"}}}}}}}}}},"/api/open/v1/auth/rotate":{"post":{"summary":"Rotate the current API key","description":"Rotate the API key behind the current bearer token and return the new raw token once.","tags":["Access & Auth"],"operationId":"rotateCurrentApiKey","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}},"/api/open/v1/auth/revoke":{"post":{"summary":"Revoke the current API key","description":"Revoke the API key behind the current bearer token and invalidate the active credential immediately.","tags":["Access & Auth"],"operationId":"revokeCurrentApiKey","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Successful response."}}}}}}