Skip to content

backend/docs: document /api/health response fields #8

Description

@CodewithJha

👋 New to open source?
Thanks for considering contributing to Mutiny.
This issue is intentionally beginner-friendly.
If you get stuck, ask questions in the comments.
We're happy to help.

Context

Cold start and README mention health checks, but field meanings for GET /api/health are not written down. The response model is HealthResponse in apps/api/src/mutiny_api/schemas.py (status, api, db, model, version, plus ops fields like mutator_mode, llm_configured, db_latency_ms, …).

Goal

Document the observed /api/health fields so operators and contributors know what “healthy” means.

Why it matters

Newcomers running ./scripts/dev.sh see a JSON blob first; a short field guide turns that into confidence instead of guesswork.

Acceptance criteria

  • Document fields observed from GET /api/health (start Hosted via ./scripts/dev.sh or uvicorn, then curl -s http://127.0.0.1:8000/api/health)
  • Link the doc from docs/README.md and/or docs/COLD_START.md
  • Optional: one integration assert that stable key names remain present
  • PR description links this issue

Suggested files

  • New or existing doc under docs/ (e.g. section in COLD_START or docs/API_HEALTH.md)
  • Optional: tests/integration/ assert on key names
  • Reference: apps/api/src/mutiny_api/schemas.py, apps/api/src/mutiny_api/app.py

Out of scope

  • Changing health payload shape, auth, or Hosted UI health widgets

Hints

  • Prefer documenting observed JSON + a one-line meaning per field over copying the entire Pydantic model docstring.
  • Call out which fields are core vs ops extras (mutator_mode, running_campaigns, …).
  • If you add a test, assert key names, not brittle values like latency.

Difficulty

S · backend docs

Docs

Metadata

Metadata

Assignees

No one assigned

    Labels

    backendAPI / Core server-sidedocsDocumentation improvementsgood first issueGood for newcomers

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions