{"openapi":"3.1.0","info":{"title":"HerculeRadar Agent API","version":"2026-09-02","description":"HerculeRadar monitors public mentions of your brand, products and competitors across X, Reddit, YouTube, LinkedIn and Threads, then uses AI to tell you which ones actually matter. The same project-scoped capabilities back the dashboard, this REST API and the MCP server.","termsOfService":"https://herculradar.com/terms"},"servers":[{"url":"https://herculradar.com","description":"Production"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"projects","description":"A workspace holding monitors, mentions and alerts."},{"name":"monitors","description":"A keyword set watched across one or more sources."},{"name":"mentions","description":"A collected public post with its AI classification."},{"name":"alerts","description":"A rule that pushes matching mentions to email or a webhook."},{"name":"usage","description":"Quota consumption and measured provider cost."}],"paths":{"/api/v1/projects":{"get":{"operationId":"list_projects","summary":"List projects","description":"Returns every project the credential can reach. An API key is scoped to one project and always returns exactly that project.","tags":["projects"],"security":[{"BearerAuth":["projects:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"projects":[{"id":"uuid","name":"Acme","plan":"starter"}]},"meta":{"capability":"list_projects","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/list_projects"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}},"post":{"operationId":"create_project","summary":"Create a project","description":"Session-authenticated only. API keys are issued against an existing project and cannot create one.","tags":["projects"],"security":[{"BearerAuth":["projects:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional but recommended. 8-128 characters. A completed response is replayed for 24 hours, so a retried write cannot create a duplicate.","schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80},"website":{"type":"string","format":"uri","nullable":true}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"id":"uuid","name":"Acme","slug":"acme","plan":"trial"},"meta":{"capability":"create_project","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/create_project"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/projects/{id}":{"get":{"operationId":"get_project","summary":"Retrieve a project","description":"One project, including its plan and mention quota.","tags":["projects"],"security":[{"BearerAuth":["projects:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"id":"uuid","name":"Acme","plan":"starter","mention_quota":1000},"meta":{"capability":"get_project","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/get_project"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/monitors":{"get":{"operationId":"list_monitors","summary":"List monitors","description":"Every keyword monitor in the project, oldest first.","tags":["monitors"],"security":[{"BearerAuth":["monitors:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"monitors":[{"id":"2c1a9f77-1b31-4d6a-9d2e-0f6a2b3c4d5e","name":"Acme","keywords":["Acme","acme.dev","@acmehq"],"exclude_keywords":["acme corp cartoon"],"sources":["x","reddit","youtube"],"group_name":"my_brand","active":true,"scan_interval_minutes":15,"last_scanned_at":"2026-09-01T09:20:00.000Z"}]},"meta":{"capability":"list_monitors","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/list_monitors"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}},"post":{"operationId":"create_monitor","summary":"Create a monitor","description":"Start watching a keyword set. Matching is literal, so include every spelling people use — the name, the domain and the @handle. The first scan runs on the next cron tick.","tags":["monitors"],"security":[{"BearerAuth":["monitors:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional but recommended. 8-128 characters. A completed response is replayed for 24 hours, so a retried write cannot create a duplicate.","schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","keywords"],"properties":{"name":{"type":"string","maxLength":80},"keywords":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string"}},"exclude_keywords":{"type":"array","maxItems":20,"items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin","threads"]}},"group_name":{"type":"string","enum":["my_brand","competitors","custom"]}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"id":"2c1a9f77-1b31-4d6a-9d2e-0f6a2b3c4d5e","name":"Acme","keywords":["Acme","acme.dev","@acmehq"],"exclude_keywords":["acme corp cartoon"],"sources":["x","reddit","youtube"],"group_name":"my_brand","active":true,"scan_interval_minutes":15,"last_scanned_at":"2026-09-01T09:20:00.000Z"},"meta":{"capability":"create_monitor","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/create_monitor"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/monitors/{id}":{"patch":{"operationId":"update_monitor","summary":"Update a monitor","description":"Change keywords, sources, group or active state. Only supplied fields are touched.","tags":["monitors"],"security":[{"BearerAuth":["monitors:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Monitor id","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional but recommended. 8-128 characters. A completed response is replayed for 24 hours, so a retried write cannot create a duplicate.","schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"exclude_keywords":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin","threads"]}},"active":{"type":"boolean","description":"false pauses collection without deleting history"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"id":"2c1a9f77-1b31-4d6a-9d2e-0f6a2b3c4d5e","name":"Acme","keywords":["Acme","acme.dev","@acmehq"],"exclude_keywords":["acme corp cartoon"],"sources":["x","reddit","youtube"],"group_name":"my_brand","active":false,"scan_interval_minutes":15,"last_scanned_at":"2026-09-01T09:20:00.000Z"},"meta":{"capability":"update_monitor","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/update_monitor"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}},"delete":{"operationId":"delete_monitor","summary":"Delete a monitor","description":"Stops collection permanently. Mentions already collected are kept. Prefer update_monitor with active:false if it may be wanted back.","tags":["monitors"],"security":[{"BearerAuth":["monitors:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Monitor id","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional but recommended. 8-128 characters. A completed response is replayed for 24 hours, so a retried write cannot create a duplicate.","schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"deleted":true,"id":"uuid"},"meta":{"capability":"delete_monitor","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/delete_monitor"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/mentions":{"get":{"operationId":"list_mentions","summary":"List mentions","description":"The core read capability. Newest first, already classified. Every parameter is optional — call it with nothing for the latest. Page with the returned nextCursor rather than an offset, so rows arriving mid-walk cannot shift the window.","tags":["mentions"],"security":[{"BearerAuth":["mentions:read"]}],"parameters":[{"name":"monitor_id","in":"query","required":false,"description":"Restrict to one monitor","schema":{"type":"string","format":"uuid"}},{"name":"source","in":"query","required":false,"description":"Platform","schema":{"type":"string","enum":["x","reddit","youtube","linkedin","threads"]}},{"name":"category","in":"query","required":false,"description":"AI category","schema":{"type":"string","enum":["bug_report","complaint","misinformation","product_idea","testimonial","other"]}},{"name":"sentiment","in":"query","required":false,"description":"AI sentiment","schema":{"type":"string","enum":["positive","neutral","negative"]}},{"name":"status","in":"query","required":false,"description":"Triage status","schema":{"type":"string","enum":["new","reviewed","done","ignored"]}},{"name":"min_urgency","in":"query","required":false,"description":"Lower bound, 0-100. 70+ is worth interrupting someone for.","schema":{"type":"integer"}},{"name":"max_urgency","in":"query","required":false,"description":"Upper bound, 0-100","schema":{"type":"integer"}},{"name":"author_handle","in":"query","required":false,"description":"Exact handle, without the @","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Case-insensitive substring of the mention text","schema":{"type":"string"}},{"name":"date_preset","in":"query","required":false,"description":"Named window, so you need not compute dates","schema":{"type":"string","enum":["today","last_24_hours","last_7_days","last_30_days","last_90_days","month_to_date","all_time"]}},{"name":"since","in":"query","required":false,"description":"ISO 8601 lower bound. Overrides date_preset.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"ISO 8601 upper bound","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-100 (default 50)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"items":[{"id":"7b0f1e3a-1c4d-4a0a-9f2b-2f4a8c1d0e11","source":"reddit","url":"https://reddit.com/r/SaaS/comments/abc123","author_handle":"ops_kate","text":"Our analytics bill tripled. Anyone know a cheaper alternative?","published_at":"2026-09-01T09:14:00.000Z","engagement":{"upvotes":128,"comments":41},"is_relevant":true,"category":"complaint","sentiment":"negative","urgency":72,"ai_summary":"User is priced out of a competitor and asking for alternatives.","status":"new"}],"nextCursor":"MjAyNi0wOS0wMVQwOToxNDowMC4wMDBafDdiMGYxZTNh","hasMore":true},"meta":{"capability":"list_mentions","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/list_mentions"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/mentions/{id}":{"get":{"operationId":"get_mention","summary":"Retrieve a mention","description":"Full text plus AI classification for one mention.","tags":["mentions"],"security":[{"BearerAuth":["mentions:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Mention id","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"id":"7b0f1e3a-1c4d-4a0a-9f2b-2f4a8c1d0e11","source":"reddit","url":"https://reddit.com/r/SaaS/comments/abc123","author_handle":"ops_kate","text":"Our analytics bill tripled. Anyone know a cheaper alternative?","published_at":"2026-09-01T09:14:00.000Z","engagement":{"upvotes":128,"comments":41},"is_relevant":true,"category":"complaint","sentiment":"negative","urgency":72,"ai_summary":"User is priced out of a competitor and asking for alternatives.","status":"new"},"meta":{"capability":"get_mention","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/get_mention"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}},"patch":{"operationId":"update_mention_status","summary":"Update mention status","description":"Move a mention through triage. Status is the only mutable field — everything else is a fact about the post.","tags":["mentions"],"security":[{"BearerAuth":["mentions:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Mention id","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional but recommended. 8-128 characters. A completed response is replayed for 24 hours, so a retried write cannot create a duplicate.","schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["new","reviewed","done","ignored"]}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"id":"7b0f1e3a-1c4d-4a0a-9f2b-2f4a8c1d0e11","source":"reddit","url":"https://reddit.com/r/SaaS/comments/abc123","author_handle":"ops_kate","text":"Our analytics bill tripled. Anyone know a cheaper alternative?","published_at":"2026-09-01T09:14:00.000Z","engagement":{"upvotes":128,"comments":41},"is_relevant":true,"category":"complaint","sentiment":"negative","urgency":72,"ai_summary":"User is priced out of a competitor and asking for alternatives.","status":"reviewed"},"meta":{"capability":"update_mention_status","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/update_mention_status"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/analytics/mentions":{"get":{"operationId":"get_mention_analytics","summary":"Mention analytics","description":"Counts for one window: totals, relevance rate, how many need attention, and breakdowns by category, sentiment, source and status. Answers \"how are we doing\" without paging the feed.","tags":["mentions"],"security":[{"BearerAuth":["mentions:read"]}],"parameters":[{"name":"date_preset","in":"query","required":false,"description":"Named window (default last_30_days)","schema":{"type":"string","enum":["today","last_24_hours","last_7_days","last_30_days","last_90_days","month_to_date","all_time"]}},{"name":"monitor_id","in":"query","required":false,"description":"Restrict to one monitor","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"window":"last_30_days","total":412,"relevant":268,"relevance_rate":0.65,"needs_attention":9,"by_category":{"complaint":91,"product_idea":74,"testimonial":62,"bug_report":28,"other":13},"by_sentiment":{"negative":121,"neutral":96,"positive":51},"by_source":{"reddit":180,"x":154,"youtube":78},"by_status":{"new":203,"reviewed":41,"done":24}},"meta":{"capability":"get_mention_analytics","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/get_mention_analytics"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/alerts":{"get":{"operationId":"list_alerts","summary":"List alert rules","description":"Every alert rule in the project.","tags":["alerts"],"security":[{"BearerAuth":["alerts:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"alerts":[{"id":"uuid","name":"Critical complaints","channel":"email","destination":"team@acme.dev","categories":["complaint"],"min_urgency":70,"active":true}]},"meta":{"capability":"list_alerts","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/list_alerts"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}},"post":{"operationId":"create_alert","summary":"Create an alert rule","description":"Empty filter arrays mean \"any\". A rule fires at most once per mention, so overlapping rules do not double-send.","tags":["alerts"],"security":[{"BearerAuth":["alerts:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional but recommended. 8-128 characters. A completed response is replayed for 24 hours, so a retried write cannot create a duplicate.","schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","destination"],"properties":{"name":{"type":"string"},"channel":{"type":"string","enum":["email","webhook"]},"destination":{"type":"string","description":"Email address, or https URL when channel is webhook"},"categories":{"type":"array","items":{"type":"string","enum":["bug_report","complaint","misinformation","product_idea","testimonial","other"]}},"sentiments":{"type":"array","items":{"type":"string","enum":["positive","neutral","negative"]}},"sources":{"type":"array","items":{"type":"string","enum":["x","reddit","youtube","linkedin","threads"]}},"min_urgency":{"type":"integer","minimum":0,"maximum":100}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"id":"uuid","name":"Critical complaints","active":true},"meta":{"capability":"create_alert","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/create_alert"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/alerts/{id}":{"delete":{"operationId":"delete_alert","summary":"Delete an alert rule","description":"Notifications stop immediately. Mentions are unaffected.","tags":["alerts"],"security":[{"BearerAuth":["alerts:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Alert id","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional but recommended. 8-128 characters. A completed response is replayed for 24 hours, so a retried write cannot create a duplicate.","schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"deleted":true,"id":"uuid"},"meta":{"capability":"delete_alert","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/delete_alert"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/usage":{"get":{"operationId":"get_usage","summary":"Plan usage and cost","description":"Plan, mentions used against the quota, and what collection cost this period. Check it before creating monitors if the project is near its limit.","tags":["usage"],"security":[{"BearerAuth":["usage:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"plan":"starter","quota_period":"monthly","mentions_included":1000,"mentions_used":412,"mentions_remaining":588,"period_start":"2026-09-01","provider_cost_usd":0.842,"cost_per_new_mention_usd":0.00204},"meta":{"capability":"get_usage","requestId":"req_9f2b4a8c1d0e","idempotencyReplayed":false,"docs":"https://herculradar.com/docs/reference/get_usage"}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/UsageLimit"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimit"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"HerculeRadar API key (hr_live_…)","description":"Scoped project API key created in the dashboard under Developer."}},"schemas":{"SuccessEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"description":"The resource. Shape depends on the capability."},"meta":{"type":"object","required":["capability","requestId","idempotencyReplayed","docs"],"properties":{"capability":{"type":"string"},"requestId":{"type":"string"},"idempotencyReplayed":{"type":"boolean"},"docs":{"type":"string","format":"uri"}}}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId","docs"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","UNAUTHORIZED","USAGE_LIMIT","FORBIDDEN","NOT_FOUND","CONFLICT","RATE_LIMIT","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"docs":{"type":"string","format":"uri"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}},"retryAfter":{"type":"integer","description":"Seconds to wait, on 429"}}}}}},"responses":{"ValidationError":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UsageLimit":{"description":"Plan quota exhausted; collection is paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"The credential is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Missing or inaccessible resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"Idempotency mismatch or duplicate in flight","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimit":{"description":"Rate limit exceeded; honour Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"x-scopes":[{"group":"projects","description":"Project settings and plan","grants":["projects:read","projects:write"]},{"group":"monitors","description":"Tracked keywords and sources","grants":["monitors:read","monitors:write"]},{"group":"mentions","description":"Collected mentions and their triage status","grants":["mentions:read","mentions:write"]},{"group":"alerts","description":"Alert rules","grants":["alerts:read","alerts:write"]},{"group":"usage","description":"Quota and provider spend","grants":["usage:read","usage:write"]},{"group":"webhooks","description":"Webhook endpoints and deliveries","grants":["webhooks:read","webhooks:write"]}],"x-mcp":{"endpoint":"https://herculradar.com/api/mcp","transport":"streamable-http","protocolVersion":"2025-06-18","tools":[{"name":"list_projects","description":"List the projects this credential can reach. Start here when you do not know the project id.","scope":"projects:read","annotations":{"title":"List projects","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"create_project","description":"Create a workspace for a brand. Only needed once per brand you monitor.","scope":"projects:write","annotations":{"title":"Create project","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"list_monitors","description":"List what is currently being watched: keywords, aliases, sources and whether each monitor is active.","scope":"monitors:read","annotations":{"title":"List monitors","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"create_monitor","description":"Start watching a brand, product or competitor. Include every spelling people actually use — the domain and the @handle as well as the name — because matching is literal.","scope":"monitors:write","annotations":{"title":"Create monitor","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"update_monitor","description":"Change a monitor’s keywords, sources or active state. Only the fields you pass change.","scope":"monitors:write","annotations":{"title":"Update monitor","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"delete_monitor","description":"Permanently remove a monitor. Mentions already collected are kept. Prefer update_monitor with active:false if the user may want it back.","scope":"monitors:write","annotations":{"title":"Delete monitor","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},{"name":"list_mentions","description":"The main read tool. Returns collected posts newest first, already classified. Call with no arguments for the latest, or filter by category, sentiment, urgency, source or a named time window. Page with the returned nextCursor.","scope":"mentions:read","annotations":{"title":"List mentions","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_mention","description":"Fetch one mention in full, with its AI classification and a link to the original post.","scope":"mentions:read","annotations":{"title":"Get mention","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"update_mention_status","description":"Move a mention through triage. Use done once it has been handled and ignored when it is not really about the brand.","scope":"mentions:write","annotations":{"title":"Update mention status","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_mention_analytics","description":"Counts for a window — totals, relevance rate, how many need attention, and breakdowns by category, sentiment and source. Use this to answer \"how are we doing\" without paging the whole feed.","scope":"mentions:read","annotations":{"title":"Get mention analytics","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"list_alerts","description":"List alert rules — what triggers a notification and where it is sent.","scope":"alerts:read","annotations":{"title":"List alerts","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"create_alert","description":"Notify an email address or https webhook when a matching mention arrives. Empty filter arrays mean \"any\".","scope":"alerts:write","annotations":{"title":"Create alert","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"delete_alert","description":"Permanently remove an alert rule. Notifications stop immediately.","scope":"alerts:write","annotations":{"title":"Delete alert","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},{"name":"get_usage","description":"Plan, mentions used against the quota, and what collection cost this period. Check before creating monitors if the user is near their limit.","scope":"usage:read","annotations":{"title":"Get usage","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}]}}