docs: document bounty sort and limit filters

[GHX5T-SOL]

/claim #426

Refs #426

Summary

• Document the current /api/v1/bounties sort and limit query parameters in docs/api-examples.md.
• Add matching summary endpoint examples for sort and limit.
• Extend the existing docs regression test so the examples stay covered.

Evidence

• app/bounty_sorting.py defines the current sort contract: newest, reward, available, and awards.
• app/bounty_api.py accepts limit from 1 to 200 and applies it after filtering/sorting for both list and summary responses.
• Existing open MRWK bounty: documentation updates and improvements #426 PRs cover different docs areas: preflight quality gate, paid proof rows, and transfer-path copy. No open PR matched this sort/limit API examples scope during final collision check.

Validation

• python3 scripts/docs_smoke.py -> docs smoke ok
• uv run --extra dev python -m pytest tests/test_docs_public_urls.py::test_api_examples_document_bounty_list_response_shape -q -> 1 passed
• uv run --extra dev python -m pytest tests/test_docs_public_urls.py -q -> 22 passed
• uv run --extra dev python -m pytest -q -> 413 passed
• uv run --extra dev ruff check . -> passed
• uv run --extra dev ruff format --check . -> 79 files already formatted
• uv run --extra dev mypy app -> success, no issues in 30 source files
• git diff --check -> clean
• gitleaks detect --no-banner --redact --source . --exit-code 1 -> no leaks found

No private keys, wallet material, cookies, OAuth state, access tokens, signatures, secrets, price claims, liquidity claims, exchange claims, bridge promises, off-ramp promises, or fabricated payout claims are included.

Summary by CodeRabbit

• Documentation

  • Enhanced Bounty API examples with additional query parameter details showing filtering, sorting, and limiting results. Documented all available sort options and valid limit ranges.

• Tests

  • Expanded test coverage for API documentation examples and query variants to ensure documentation accuracy.

[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: 5885c3ae-4176-4a21-ab41-69d5c3344329

📥 Commits

Reviewing files that changed from the base of the PR and between 12c3dbd and e45298b.

📒 Files selected for processing (2)

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

---

📝 Walkthrough

Walkthrough

This PR updates the public bounty API documentation and tests to document and validate query parameters for filtering and limiting results. The open bounties summary examples now include sort and limit parameters, with expanded guidance on sorting options and range constraints. Tests are updated to verify the documented examples and parameter behaviors.

Changes

Bounty API Query Parameter Documentation and Tests

Layer / File(s)	Summary
API documentation examples and parameter guidance docs/api-examples.md	Bounty API example queries updated to include sort and limit parameters (sort=available, sort=awards, limit values). Documentation expanded to describe sort options (newest, reward, available, awards) and valid limit ranges, and /api/v1/bounties/summary guidance updated to note support for status, q, sort, and limit filters.
Test assertions for documented examples tests/test_docs_public_urls.py	Test assertions expanded to validate the additional API URL examples and documentation text describing query parameter behavior, including sort defaults, per-award reward sorting, available slots semantics, and limit ranges. Capacity-total assertions split into separate, more specific checks.

Possibly related PRs

• ramimbo/mergework#442: Both PRs update documentation and examples for the /api/v1/bounties/summary endpoint—this PR extends examples with sort and limit variants, while that PR adds the endpoint and basic status/q examples.
• ramimbo/mergework#441: Main PR documents sort/limit query variants for /api/v1/bounties and /api/v1/bounties/summary; retrieved PR implements validated limit handling on those same endpoints.
• ramimbo/mergework#311: Both PRs update /api/v1/bounties/summary examples and test assertions; retrieved PR introduces the endpoint, this PR extends its documentation.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately names the changed surface and clearly summarizes the main change: documenting bounty sort and limit filters in the API examples.
Description check	✅ Passed	The description includes all required template sections with substantive content: summary, evidence, validation steps, and MRWK reference. All test checks are reported as passing.
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	No investment, price, cash-out, fabricated payout, or problematic security disclosure claims found. MRWK correctly described as bounty reward mechanism with proper key-handling guidance.
Bounty Pr Focus	✅ Passed	PR diff matches stated files with bounty sort and limit documentation and tests. Implementation support verified. Scope is focused and avoids unrelated changes.

_{✏️ 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.}

[weilixiong]

LGTM — docs and tests only, zero risk.

Verified:

• git diff --check clean
• tests/test_docs_public_urls.py: 17/17 passed (0.10s)
• Changes: +20 lines across 2 files (docs/api-examples.md + tests/test_docs_public_urls.py)
• Documents sort and limit query params for /api/v1/bounties and /api/v1/bounties/summary
• Test assertions match documented examples exactly

[yannickvilleneuve-hash]

Reviewed current head e45298bff9c857886b6f6137e41b2e024b1b1cb0.

No blockers found. The docs change is narrowly scoped to docs/api-examples.md and tests/test_docs_public_urls.py, and it matches the current bounty API contract:

• app/bounty_api.py accepts optional status, q, sort, and limit for both /api/v1/bounties and /api/v1/bounties/summary.
• limit is constrained to 1..200 and applied after filtering/sorting.
• app/bounty_sorting.py defines newest, reward, available, and awards with the same meanings documented here.
• The updated docs test pins the new examples and wording, while existing API/page tests cover the underlying behavior.

Validation:

• uv run --extra dev python -m pytest tests/test_docs_public_urls.py::test_api_examples_document_bounty_list_response_shape tests/test_bounty_api_routes.py::test_bounty_api_limit_caps_filtered_rows tests/test_bounty_api_routes.py::test_bounty_api_limit_rejects_out_of_range_values tests/test_bounty_pages.py::test_bounties_page_and_api_sort_public_rows -q -> 4 passed
• uv run --extra dev python -m pytest tests/test_docs_public_urls.py tests/test_bounty_api_routes.py::test_bounty_api_limit_caps_filtered_rows tests/test_bounty_api_routes.py::test_bounty_api_limit_rejects_out_of_range_values tests/test_bounty_pages.py::test_bounties_page_and_api_sort_public_rows -q -> 25 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
• git diff --check origin/main...HEAD -> clean
• Live API check: GET /api/v1/bounties?status=open&sort=available&limit=2 returned two rows ordered by available_mrwk descending (920, then 800) at review time.
• GitHub commit status for e45298bff9c857886b6f6137e41b2e024b1b1cb0 -> success (CodeRabbit).

No public artifact hygiene issues found; this is API docs/test coverage only and does not add price, exchange, liquidity, or off-ramp claims.