Update pkg/api/README.md to align with current codebase

[redhat-ship-help]

Summary

The API README (pkg/api/README.md) was written circa 2021 (OCP 4.9 era) and documented only a handful of endpoints with Bugzilla references and outdated response examples. The codebase has since grown to ~60+ API endpoints across many functional areas.

Changes

This update rewrites the README to:

• Document all current API endpoints organized by functional area (release health, jobs, tests, component readiness, payloads, chat, etc.)
• Add a Capabilities section explaining how endpoints are gated by server capabilities (local_db, component_readiness, chat, etc.)
• Document CRUD endpoints for labels, symptoms, and triages with their HTTP methods
• Add sections for new functional areas: component readiness, payloads, incidents, feature gates, chat, and MCP endpoints
• Point readers to the self-describing /api endpoint for live discovery of available endpoints
• Remove outdated content: example responses with stale data (Bugzilla IDs, testgrid URLs, OCP 4.9 references)
• Retain the still-accurate filtering and sorting documentation

The endpoint list was generated by reviewing the route registration in pkg/sippyserver/server.go.

/cc @openshift/sippy-maintainers

Summary by CodeRabbit

• Documentation
  • Clarified API intro: endpoint is self-describing and returns a JSON list of available endpoints.
  • Noted endpoint availability is capability-gated and added a Capabilities section documenting flags and GET /api/capabilities.
  • Replaced verbose per-endpoint docs with a Common Parameters section and a consolidated Endpoint Reference grouped by functional areas.
  • Documented new/renamed endpoints (tests v2, component readiness/triage, feature gates, MCP).
  • Expanded MCP docs with session-aware tool-calling details and an “Adding New MCP Tools” procedure.

[openshift-ci-robot]

Pipeline controller notification
This repo is configured to use the pipeline controller. Second-stage tests will be triggered either automatically or after lgtm label is added, depending on the repository configuration. The pipeline controller will automatically detect which contexts are required and will utilize /test Prow commands to trigger the second stage.

For optional jobs, comment /test ? to see a list of all defined jobs. To trigger manually all jobs from second stage use /pipeline required command.

This repository is configured in: automatic mode

[openshift-ci]

@redhat-ship-help: GitHub didn't allow me to request PR reviews from the following users: openshift/sippy-maintainers.

Note that only openshift members and repo collaborators can review this PR, and authors cannot review their own PRs.

Details

In response to this:

Summary

The API README (pkg/api/README.md) was written circa 2021 (OCP 4.9 era) and documented only a handful of endpoints with Bugzilla references and outdated response examples. The codebase has since grown to ~60+ API endpoints across many functional areas.

Changes

This update rewrites the README to:

• Document all current API endpoints organized by functional area (release health, jobs, tests, component readiness, payloads, chat, etc.)
• Add a Capabilities section explaining how endpoints are gated by server capabilities (local_db, component_readiness, chat, etc.)
• Document CRUD endpoints for labels, symptoms, and triages with their HTTP methods
• Add sections for new functional areas: component readiness, payloads, incidents, feature gates, chat, and MCP endpoints
• Point readers to the self-describing /api endpoint for live discovery of available endpoints
• Remove outdated content: example responses with stale data (Bugzilla IDs, testgrid URLs, OCP 4.9 references)
• Retain the still-accurate filtering and sorting documentation

The endpoint list was generated by reviewing the route registration in pkg/sippyserver/server.go.

/cc @openshift/sippy-maintainers

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: fa1b14e6-392a-4444-b6a9-eb503815cbf4

📥 Commits

Reviewing files that changed from the base of the PR and between 8c307b0 and cb5fb26.

📒 Files selected for processing (1)

• pkg/api/README.md

---

Walkthrough

Rewrote pkg/api/README.md: intro now states the API is self-describing and capability-gated; added a Capabilities section and GET /api/capabilities; replaced verbose per-endpoint docs with Common Parameters and a consolidated Endpoint Reference; expanded MCP tool-calling interface and “Adding New MCP Tools” guidance.

Changes

Cohort / File(s)

Summary

API documentation pkg/api/README.md

Completely restructured API docs: updated intro and backwards-compatibility note; added Capabilities section and GET /api/capabilities; removed detailed per-endpoint prose and large examples; introduced Common Parameters and an Endpoint Reference grouping endpoints (Release Health, Jobs, Job Run Labels/Symptoms CRUD, Tests including GET /api/tests/v2, Install & Upgrade, Component Readiness and triage endpoints, Pull Requests & Repositories, Payloads, Incidents, Feature Gates including GET /api/feature_gates, Chat, Utility, and MCP under /mcp/v1/); expanded MCP section with session-aware tool interface, advertised tools, and “Adding New MCP Tools” describing the MCPTool interface and registration points.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Go Error Handling	⚠️ Warning	The codebase contains multiple violations of Go error handling best practices including improper error wrapping and inappropriate panic() calls.	Replace fmt.Errorf() %v with %w for error wrapping and remove panic() calls from goroutines and utility functions, propagating errors instead.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Sql Injection Prevention	✅ Passed	SQL injection check not applicable as PR contains only documentation updates to pkg/api/README.md with no code changes.
Excessive Css In React Should Use Styles	✅ Passed	This PR only modifies pkg/api/README.md, a Markdown documentation file. There are no React components, JavaScript files, or CSS styling changes, so this check does not apply.
Single Responsibility And Clear Naming	✅ Passed	The PR contains only documentation updates to pkg/api/README.md with no changes to code files or entities.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with 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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: redhat-ship-help
Once this PR has been reviewed and has the lgtm label, please assign smg247 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[openshift-ci]

Hi @redhat-ship-help. Thanks for your PR.

I'm waiting for a openshift member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[stbenjam]

@redhat-ship-help Do you respond to comments? This is likely to just get out of date again.

[stbenjam]

/ok-to-test

[openshift-ci-robot]

Scheduling required tests:
/test e2e

[openshift-ci]

@redhat-ship-help: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.