Refs #426: Document health response shape

[Baijack-star]

Refs #426

Summary

• document /health in docs/api-examples.md as the lightweight liveness and ledger-height endpoint
• add the current public response shape with ok, service, ticker, and ledger_height
• add a docs regression so the endpoint is not only listed without its fields

Evidence

• app/main.py registers GET /health and returns health_status(session).
• app/status.py returns only ok, service, ticker, and ledger_height for the health endpoint.
• Live unauthenticated checks on 2026-05-28 returned HTTP 200 JSON from both public hosts:
  • https://api.mrwk.ltclab.site/health -> {"ledger_height":792,"ok":true,"service":"mergework","ticker":"MRWK"}
  • https://mrwk.ltclab.site/health -> same shape
• Bounty MRWK bounty: documentation updates and improvements #426 / internal bounty 72 was open with 2 award slots and no active attempts before submission.

Validation

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ./.venv/bin/python scripts/docs_smoke.py -> docs smoke ok
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ./.venv/bin/python -m pytest tests/test_docs_public_urls.py::test_api_examples_document_health_response_shape tests/test_docs_public_urls.py::test_api_examples_document_internal_bounty_ids -q -> 2 passed
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 ./.venv/bin/python -m pytest tests/test_docs_public_urls.py -q -> 24 passed
• ./.venv/bin/python -m ruff check tests/test_docs_public_urls.py -> passed
• ./.venv/bin/python -m ruff format --check tests/test_docs_public_urls.py -> already formatted
• git diff --check origin/main...HEAD -> clean

No private data, cookies, tokens, wallet material, signatures, price claims, liquidity/exchange/off-ramp claims, bridge promises, or fabricated payout claims are included.

Summary by CodeRabbit

• Documentation

  • Added comprehensive /health API endpoint documentation including curl command example and sample JSON response with system liveness and ledger height information.
  • Reorganized API examples section naming for clearer categorization of health and status monitoring resources.

• Tests

  • Added automated validation test to ensure health endpoint documentation includes expected response fields and usage examples.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 14bb97a5-57f7-4aac-ae74-13ec9088f781

📥 Commits

Reviewing files that changed from the base of the PR and between d8532d4 and 49ae4b0.

📒 Files selected for processing (2)

• docs/api-examples.md
• tests/test_docs_public_urls.py

---

📝 Walkthrough

Walkthrough

Updated API documentation to include a new /health endpoint with curl example and sample JSON response, and added test validation to ensure the documentation contains the endpoint example, expected response fields, and explanatory text about the liveness and ledger-height check.

Changes

Health Endpoint Documentation

Layer / File(s)	Summary
/health endpoint documentation and validation docs/api-examples.md, tests/test_docs_public_urls.py	Section header renamed from "Status And Bounties" to "Health, Status, And Bounties". Added /health endpoint documentation with curl example and JSON response showing is_alive and ledger_height fields. Added test test_api_examples_document_health_response_shape() to verify the documentation includes the endpoint example, response structure, and descriptive text about the liveness check.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly names the changed surface—documenting the health response shape—and is concrete and appropriately scoped.
Description check	✅ Passed	Description includes all required sections: summary of changes, evidence of implementation, test validation, bounty reference, and confirmation of no sensitive data.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Mergework Public Artifact Hygiene	✅ Passed	PR adds technical API documentation for the /health endpoint. No investment, price, cash-out, payout, or security claims present. MRWK only mentioned as API response ticker.
Bounty Pr Focus	✅ Passed	PR changes match stated files and scope: renamed section, added /health API docs with response shape, added regression test. No unrelated changes. Test assertions align with documented content.

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

---

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

[bitdamii]

Reviewed PR #553 at current head 49ae4b06220044dfc47126a70eff7de375e55e3a as non-author bitdamii.

Evidence: inspected docs/api-examples.md, tests/test_docs_public_urls.py, and the existing /health implementation in app/main.py and app/status.py; confirmed the docs now separate lightweight /health monitoring from full /api/v1/status, list the exact public response fields (ok, service, ticker, ledger_height), and add a regression so the endpoint is not documented without its shape. The sample matches health_status() and does not add payout, price, liquidity, off-ramp, wallet-secret, or private-data claims.

Validation: uv run --extra dev python -m pytest tests/test_docs_public_urls.py::test_api_examples_document_health_response_shape tests/test_status.py::test_health_status_reports_current_ledger_height tests/test_api_mcp.py::test_health_status_and_bounty_api -q -> 3 passed; uv run --extra dev python -m pytest tests/test_docs_public_urls.py tests/test_status.py tests/test_api_mcp.py::test_health_status_and_bounty_api -q -> 27 passed; uv run --extra dev python scripts/docs_smoke.py -> docs smoke ok; uv run --extra dev ruff check docs/api-examples.md tests/test_docs_public_urls.py passed; uv run --extra dev ruff format --check tests/test_docs_public_urls.py passed; uv run --extra dev python -m mypy app/status.py app/main.py passed; git diff --check origin/main...HEAD clean. GitHub Quality/readiness/docs/image checks and CodeRabbit are successful with no actionable comments.

No blocker found in this reviewed slice.

[tinyopsstudio]

Reviewed PR #553 at 49ae4b06220044dfc47126a70eff7de375e55e3a for the documented /health response shape.

Evidence checked:

• inspected docs/api-examples.md, tests/test_docs_public_urls.py, app/main.py, app/status.py, tests/test_status.py, and tests/test_api_mcp.py;
• confirmed /health is registered in app/main.py and returns health_status(session);
• confirmed health_status() returns only ok, service, ticker, and ledger_height;
• confirmed the docs now distinguish lightweight /health polling from the heavier /api/v1/status counters and bounty-list paths;
• confirmed the new docs regression checks both the curl -s "$API_HOST/health" example and all documented response fields.

Validation:

• ad hoc TestClient probe: /health returned 200, exactly the keys ledger_height, ok, service, and ticker, matched health_status(session), and reported ledger height 2 after genesis plus one bounty row
• focused tests: tests/test_docs_public_urls.py::test_api_examples_document_health_response_shape, tests/test_status.py::test_health_status_reports_current_ledger_height, and tests/test_api_mcp.py::test_health_status_and_bounty_api -> 3 passed
• scripts/docs_smoke.py -> docs smoke ok
• tests/test_docs_public_urls.py tests/test_status.py tests/test_api_mcp.py::test_health_status_and_bounty_api -q -> 27 passed
• full test suite -> 415 passed
• Ruff check on docs/api-examples.md, tests/test_docs_public_urls.py, app/status.py, and app/main.py -> passed
• Ruff format check on the Python files -> 3 files already formatted
• mypy app/status.py app/main.py -> success
• git diff --check origin/main...HEAD -> clean

Assessment: no blocker found in this docs/test slice. The documented shape matches the implementation and stays within public liveness/status fields, without adding price, liquidity, exchange, bridge, off-ramp, private-key, or fabricated payout claims.

[eliasx45]

Reviewed current head 49ae4b06220044dfc47126a70eff7de375e55e3a for the /health documentation change.

No blocker found. The PR is narrow: it documents /health as the lightweight liveness/ledger-height endpoint, keeps /api/v1/status positioned for heavier counters and treasury data, and adds a docs regression so the health endpoint is not listed without its response fields. The documented keys match app.status.health_status() and the registered GET /health route.

Evidence checked:

• inspected docs/api-examples.md, tests/test_docs_public_urls.py, app/main.py, app/status.py, tests/test_status.py, and tests/test_api_mcp.py;
• confirmed /health returns health_status(session) from app/main.py;
• confirmed health_status() exposes ok, service, ticker, and ledger_height only;
• confirmed the docs describe /health as a small polling endpoint and keep /api/v1/status for broader counters;
• public probes returned HTTP 200 from both https://api.mrwk.ltclab.site/health and https://mrwk.ltclab.site/health, with the documented key shape and live ledger_height 831.

Validation performed:

• .\.venv\Scripts\python.exe -m pytest tests\test_docs_public_urls.py::test_api_examples_document_health_response_shape tests\test_status.py::test_health_status_reports_current_ledger_height tests\test_api_mcp.py::test_health_status_and_bounty_api -q -> 3 passed.
• .\.venv\Scripts\python.exe scripts\docs_smoke.py -> docs smoke ok.
• .\.venv\Scripts\python.exe -m pytest tests\test_docs_public_urls.py tests\test_status.py tests\test_api_mcp.py::test_health_status_and_bounty_api -q -> 27 passed.
• .\.venv\Scripts\python.exe -m ruff check tests\test_docs_public_urls.py app\status.py app\main.py -> passed.
• .\.venv\Scripts\python.exe -m ruff format --check tests\test_docs_public_urls.py app\status.py app\main.py -> 3 files already formatted.
• .\.venv\Scripts\python.exe -m mypy app\status.py app\main.py -> success.
• .\.venv\Scripts\python.exe -m pytest -q -> 415 passed.
• git diff --check origin/main...HEAD -> clean.
• GitHub PR checks are passing, including CodeRabbit and the quality/readiness/docs/image workflow.

This looks mergeable from my reviewed slice.

[ramimbo]

Bounty #426 is now filled and closed, so this PR is not currently payable under that bounty. Leaving mrwk:needs-info here; please retarget only if a future live bounty explicitly covers this work, or confirm that you want it considered as a non-bounty contribution.

[barnacleagent-svg]

Verdict: APPROVED

Scope: Documents /health response shape in docs/api-examples.md. Adds curl example and JSON response with ok, service, ticker, ledger_height fields.

Checklist:

• Diff: +30/-2 across 2 files
• Documentation-only, no logic change
• Tests verify new content

Conclusion: Clean documentation addition. Ready to merge.

[wangedmund77-cmyk]

Reviewed current head 49ae4b06220044dfc47126a70eff7de375e55e3a for bounty #578.

Evidence checked:

• Inspected docs/api-examples.md and tests/test_docs_public_urls.py.
• git diff --check origin/main...origin/pr/553 returned clean.
• Ran uv run pytest tests/test_docs_public_urls.py -q on the PR head: 24 passed.
• GitHub mergeability is clean/MERGEABLE.

No blocker found. The docs now show the public /health response fields without implying private/admin data, and the docs URL smoke coverage was updated with the new live API reference.