Conversation
aantn
commented
Aug 24, 2025
aantn
commented
- Move API docs out of a subpage and into the parent Robusta Pro features.
- Other small changes for clarity
WalkthroughRemoved two documentation pages, added Sphinx redirects for them, expanded and reformatted the Send Alerts API doc (content, schema, examples, troubleshooting, testing), adjusted Robusta Pro features text, and updated the docs index to list individual API pages. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (7)
docs/configuration/exporting/send-alerts-api.rst (5)
151-154: Normalize Authorization placeholder to a single conventionThe example uses “API-KEY” while the header description uses “TOKEN_HERE”. Pick one (e.g., API_KEY) for consistency across the page.
- --header 'Authorization: Bearer API-KEY' \ + --header 'Authorization: Bearer API_KEY' \- * - ``Authorization`` - - Bearer token for authentication (e.g., ``Bearer TOKEN_HERE``). The token must have the necessary permissions to submit alerts. + * - ``Authorization`` + - Bearer token for authentication (e.g., ``Bearer API_KEY``). The token must have the necessary permissions to submit alerts.Also applies to: 193-195
180-182: Clarify where to find ACCOUNT_ID for SaaS vs self-hosted“generated_values.yaml” applies to self-hosted; SaaS users will likely look in the UI. Suggest clarifying both.
-- ``ACCOUNT_ID``: Your account ID, which can be found in your ``generated_values.yaml`` file. +- ``ACCOUNT_ID``: Your account ID (SaaS: Settings → Account in the Robusta UI; self-hosted: in your ``generated_values.yaml``).
58-60: Use JSON-native type names (“array”, “object”) instead of Python-specific (“list”, “dict”)The page is API-focused and shows JSON payloads. Using JSON type names improves clarity and avoids language bias.
- - list + - array- * - ``labels`` - - dict + * - ``labels`` + - object- * - ``annotations`` - - dict + * - ``annotations`` + - objectApply the same “array/object” terminology anywhere else applicable on this page.
Also applies to: 108-115
171-174: Example request: include subject_type/name for completenessThe schema lists subject_type and subject_name but the example omits them. Adding them helps integrators map these fields correctly.
"cluster": "prod-cluster-1", + "subject_type": "service", + "subject_name": "test-service", "subject_namespace": "prod", "subject_node": "gke-prod-cluster-1-node-1"
236-239: Troubleshooting: “Wait 10 minutes” guidance — verify or scope itStartup time can vary by environment. If 10 minutes is specific to a known install profile, say so; otherwise consider “a few minutes” or provide readiness indicators (pods, health checks).
docs/conf.py (1)
202-205: Add “docs/…” prefixes too for belt-and-suspenders compatibilityElsewhere in this list, some old paths include a “docs/…” prefix. If external links ever referenced the generated HTML under that prefix, adding parallel redirects avoids 404s.
"advanced/index.html": "/master/setup-robusta/installation/index.html", "configuration/exporting/exporting-data.html": "/master/configuration/exporting/send-alerts-api.html", - "configuration/alertmanager-integration/troubleshooting-alertmanager.html": "/master/configuration/exporting/send-alerts-api.html" + "configuration/alertmanager-integration/troubleshooting-alertmanager.html": "/master/configuration/exporting/send-alerts-api.html", + "docs/configuration/exporting/exporting-data.html": "/master/configuration/exporting/send-alerts-api.html", + "docs/configuration/alertmanager-integration/troubleshooting-alertmanager.html": "/master/configuration/exporting/send-alerts-api.html"docs/configuration/exporting/robusta-pro-features.rst (1)
36-37: Prefer a sub-heading over bold text for “Robusta API Reference”As a section lead-in, using a proper sub-heading renders better in the ToC and supports deep-linking.
-**Robusta API Reference** - Comprehensive APIs for exporting alert history, generating reports, and sending custom alerts programmatically. +Robusta API Reference +--------------------- + A set of APIs for exporting alert history, generating reports, and sending alerts programmatically.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (6)
docs/conf.py(1 hunks)docs/configuration/alertmanager-integration/troubleshooting-alertmanager.rst(0 hunks)docs/configuration/exporting/exporting-data.rst(0 hunks)docs/configuration/exporting/robusta-pro-features.rst(2 hunks)docs/configuration/exporting/send-alerts-api.rst(7 hunks)docs/index.rst(1 hunks)
💤 Files with no reviewable changes (2)
- docs/configuration/alertmanager-integration/troubleshooting-alertmanager.rst
- docs/configuration/exporting/exporting-data.rst
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: run_tests
- GitHub Check: run_tests
- GitHub Check: Deploy docs
- GitHub Check: Deploy docs
🔇 Additional comments (7)
docs/configuration/exporting/send-alerts-api.rst (3)
88-91: Confirm allowed values for priorityThe set includes both “critical/high/medium/low” and “error/debug”. Verify these are the exact values accepted by the backend validator and case sensitivity requirements (e.g., lower-case only). If there’s a canonical enum, link or reference it.
33-34: Batch size limit: please confirm 1000 per requestIf this 1000 limit is enforced server-side, keep it. If it’s a guideline or subject to change, consider “currently up to 1000” and/or note rate limits.
18-26: Nice addition: Integration overview before the API detailsClear, user-friendly framing that helps readers choose between pre-built integrations and the API path.
docs/conf.py (1)
202-205: Redirects for removed pages — looks correctBoth old pages now point to the new Send Alerts API doc. Trailing comma after the previous item is good cleanup.
docs/configuration/exporting/robusta-pro-features.rst (2)
43-44: Terminology alignment: “Send Alerts API”Good rename from “Custom Alert API” to “Send Alerts API” — matches the new doc and is clearer for users.
67-67: Helpful pointerThe closing line directing readers to the individual API references is clear and consistent with the new structure.
docs/index.rst (1)
86-90: Index updated to list individual API docs — LGTMThe Pro Features section now surfaces the specific API pages directly, which improves discoverability.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/configuration/exporting/send-alerts-api.rst (1)
27-28: Duplicate “Send Alerts API” heading — rename inner section to avoid conflicting anchorsThis repeats the H1 from Line 1 and can create duplicate anchors/ToC noise (especially with autosectionlabel enabled). Rename this inner heading to “Endpoint” (or remove it).
Apply:
-Send Alerts API ---------------- +Endpoint +--------
🧹 Nitpick comments (6)
docs/configuration/exporting/send-alerts-api.rst (6)
35-39: Prefer a code block for the HTTP method/URL instead of a caret-underlined titleRendering an URL-as-title with carets is unusual in our docs and makes deep-linking less clear. A small restructure reads better and avoids overlong underline lines.
Example:
-.. _send-alerts-api: - -POST https://api.robusta.dev/api/alerts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _send-alerts-api: + +Endpoint +-------- + +.. code-block:: http + + POST /api/alerts HTTP/1.1 + Host: api.robusta.dev
149-176: Example: consider adding Accept header and a second alert to demonstrate batchingMinor polish: many APIs encourage
Accept: application/json. Also, including two alerts showcases the batch behavior.curl --location --request POST 'https://api.robusta.dev/api/alerts' \ --header 'Authorization: Bearer API-KEY' \ --header 'Content-Type: application/json' \ + --header 'Accept: application/json' \ --data-raw '{ "account_id": "ACCOUNT_ID", "alerts": [ { "title": "Test Service Down", "description": "The Test Service is not responding.", "source": "monitoring-system", "priority": "high", "aggregation_key": "test-service-issues", "failure": true, "starts_at": "2024-10-07T10:00:00Z", "labels": { "environment": "production" }, "annotations": { "env1": "true" }, "cluster": "prod-cluster-1", "subject_namespace": "prod", "subject_node": "gke-prod-cluster-1-node-1" - } + }, + { + "title": "Background job latency", + "description": "Latency p95 > 2s", + "source": "custom-metrics", + "priority": "warning", + "aggregation_key": "job-latency", + "labels": { "job": "worker" } + } ] }'
211-211: Use literal inline code for status codesIn reStructuredText, single backticks are interpreted text. Use double backticks for literal code.
-- **Status Code**: `200 OK` +- **Status Code**: ``200 OK``
225-226: Same here: fix inline code for examples of error codes-- **Status Code**: Varies based on the error (e.g., `400 Bad Request`, `500 Internal Server Error`). +- **Status Code**: Varies based on the error (e.g., ``400 Bad Request``, ``500 Internal Server Error``).
7-14: Intro benefits are crisp; consider trimming “and more!”Great overview. Minor tone nit: “and more!” can be dropped for a slightly more formal feel consistent with the rest of the page.
-* and more!
80-83: Description field punctuation consistencySome descriptions end with a period, others don’t. Standardize for uniformity.
- - A detailed description of the alert + - A detailed description of the alert.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/configuration/exporting/send-alerts-api.rst(7 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: run_tests
- GitHub Check: run_tests
- GitHub Check: Deploy docs
🔇 Additional comments (8)
docs/configuration/exporting/send-alerts-api.rst (8)
40-61: Request Body section reads well and clarifies batching limitNice improvement: clear table, explicit required fields, and max 1000 alerts per request.
178-182: Nice: clear guidance on where to find Account ID and create API keysThis will reduce support questions.
200-210: Success response block is concise and consistent with headers aboveLGTM.
260-265: Link verification succeeded:embedded-prometheus.rstexists and the relative path is correctThe file
docs/configuration/alertmanager-integration/embedded-prometheus.rstwas found, which matches the link target../alertmanager-integration/embedded-prometheusfromdocs/configuration/exporting/send-alerts-api.rst. No changes required.
227-241: sphinx_design extension already enabledConfirmed that
sphinx_designappears in theextensionslist indocs/conf.py(line 50), so the.. tab-set::and.. tab-item::directives will work as intended.
280-280: Avoid URL shorteners in docsI ran a search for any existing
robusta.dev/slackorrobusta.ai/slackURLs in the repo and found none, which suggests a canonical redirect may not yet exist. Before swapping out the Bit.ly link, please verify whether ahttp(s)://robusta.dev/slackredirect is live or planned. If it is, update the doc as shown; otherwise, either deploy that redirect first or continue using the Bit.ly link until the canonical URL is available.• File:
docs/configuration/exporting/send-alerts-api.rst
Lines around 280: replace the Bit.ly link once the canonical redirect existsSuggested diff:
-* Join our `Slack community <https://bit.ly/robusta-slack>`_ for direct support +* Join our `Slack community <https://robusta.dev/slack>`_ for direct support
62-143: Verifypriorityenum andaggregation_keyrequirement against the backend API specI searched this repository for any OpenAPI/JSONSchema definitions or server-side validation rules and didn’t find a definitive schema enforcing:
- The exact set of
priorityvalues (critical,high,medium,error,warning,info,low,debug).- Whether
aggregation_keyis truly required by the API.Please double-check the upstream API specification or server validation to ensure these match. If you confirm that
aggregation_keyis optional, update the docs accordingly. For example:- * - ``aggregation_key`` - - string - - A key to group alerts that are related. - - Yes + * - ``aggregation_key`` + - string + - A key to group alerts that are related (used for de-duplication/grouping). + - No— After you verify, please either update the documentation or confirm that these fields are indeed required/limited exactly as shown.
23-25: No changes for Alert Sources linkThe
:doc:Alert Sources <../index>link insend-alerts-api.rstalready targetsdocs/configuration/index.rst`, which is the dedicated “Alert Sources” document. No update is needed here.
2 participants
