docs: add complete REST API reference for ADK web server

[akshay-kumar-bm]

Summary

Closes google/adk-python#2511

The existing REST API reference page (docs/api-reference/rest/index.md) only documented two endpoints (/run and /run_sse). This PR expands it to cover all 40 endpoints exposed by the ADK web server.

What's added

• System — /health, /version, /list-apps
• Agent Execution — POST /run, POST /run_sse, WebSocket /run_live
• Sessions — full CRUD + state patch (6 endpoints)
• Artifacts — upload, versioning, metadata (8 endpoints)
• Memory — PATCH /memory
• Events — event graph visualisation
• Eval — eval sets, eval cases, run, results, metrics (9 endpoints)
• Debug — trace endpoints (dev only)
• Builder — agent editor endpoints (web UI only)
• Data models — Content, Event, Session, ArtifactVersion with field-level descriptions and JSON examples

All endpoint descriptions were derived directly from the source in src/google/adk/cli/adk_web_server.py and src/google/adk/cli/fast_api.py. The deprecated POST /sessions/{session_id} endpoint is included and marked as deprecated.

Test plan

• Verify rendered docs locally with mkdocs serve
• Spot-check a running adk web server at /docs to confirm endpoint signatures match
• Confirm all internal doc links resolve correctly

---

cc @polong-lin @boyangsvl

[netlify]

✅ Deploy Preview for adk-docs-preview ready!

Name	Link
🔨 Latest commit	402b137
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/69c40f0e50d9360008ca2b07
😎 Deploy Preview	https://deploy-preview-1494--adk-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[koverholt]

Thanks for the PR @akshay-kumar-bm! I didn't realize we still had hand-written REST API docs, so I appreciate you flagging the gap.

After reviewing this, rather than hand-maintaining these (which will drift from the source), we can auto-generate the reference from the FastAPI OpenAPI spec in adk-python, consistent with how we handle other generated API docs per CONTRIBUTING.md. Closing in favor of that approach, which I'll open a new PR for.

[koverholt]

And to clarify, if you or others are still interested in improving the REST API docs, adding Field(description=...) annotations and examples to the Pydantic models, and docstrings and responses to the route handlers in the upstream adk-python repo would be valuable.

For example, RunAgentRequest and Session in src/google/adk/cli/adk_web_server.py and many others currently have no field descriptions. Those would flow through to the generated Swagger UI automatically after #1500 is merged.

[akshay-kumar-bm]

@koverholt Started my open-source contribution journey by enhancing API documentation with additional details and improvements. Really enjoyed the process.

[akshay-kumar-bm]

@koverholt

Raised a PR to update the default section in FastAPI:

• Added API documentation and descriptions
• Included field (desc) updates for the default section endpoint

Would appreciate a review and feedback. I’ll proceed with updating the remaining endpoints based on your suggestions.

PR: google/adk-python#5031