Document every API endpoint with request/response examples

[mikewheeleer]

Document the full HTTP API surface with examples

Description

README.md describes only setup and scripts; it documents none of the ~25 routes the service actually exposes in src/index.ts (pairs, pair-meta, quote, bulk quote, api-keys, webhooks, events, config, metrics, stats, admin). New contributors must read the source to learn the API. This issue produces a complete endpoint reference.

Requirements and context

• Repository scope: StableRoute-Org/Stableroute-backend only.
• Create docs/api.md (create file) documenting each route: method, path, params/body schema, success and error responses, and a curl example.
• Document the canonical error envelope { error, message, requestId } once and reference it.
• Document operational headers: X-Request-Id, Retry-After, ETag, and the security headers.
• Link docs/api.md from README.md.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/api-docs-21-endpoint-reference
• Implement changes
  • Write code in: n/a (docs); cross-check every entry against src/index.ts and the /api/v1/openapi.json handler.
  • Add documentation: create docs/api.md; update README.md.
  • Ensure examples match actual status codes and bodies.
  • Validate security: note which routes will require auth once guards land.
• Test and commit

Test and commit

• Run npm run build and npm test to confirm nothing regressed.
• Spot-check several curl examples against a locally running npm run dev.
• Paste the rendered docs outline in the PR.

Example commit message

docs(api): add complete endpoint reference with curl examples

Guidelines

• Minimum 95 percent test coverage for impacted code (n/a for docs; keep existing tests green).
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the StableRoute community on Discord for questions, reviews, and faster merges: https://discord.gg/37aCpusvx
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[Kuhai9801]

Hi, I can take this. I’ll add a docs/api.md endpoint reference cross-checked against src/index.ts, including error envelopes, operational headers, and curl examples.