Document the full HTTP API surface in the README and align it with OpenAPI

[mikewheeleer]

Document the full HTTP API surface

Description

The README.md still describes the service as exposing only "Health check, version, and placeholders for usage/billing APIs," but src/index.ts now implements 40+ endpoints across usage, billing, settlement, services, api-keys, webhooks, events, admin, and metrics. New contributors have no accurate map of the API. This issue brings the README in line with reality and the served OpenAPI doc.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Replace the "Endpoints" line in README.md with a grouped table of every route, method, purpose, and key request/response fields.
• Cross-link the live GET /api/v1/openapi.json and ensure the README and OpenAPI list the same paths.
• Document the standard error envelope (error, message, requestId) and the common status codes (400/404/409/413/429/503).
• Note the in-memory/non-durable nature of the current stores.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/docs-23-api-reference
• Implement changes
  • Write code in: no production code change; documentation only.
  • Write comprehensive tests in: optionally add a src/openapi-parity.test.ts asserting README routes match the OpenAPI paths.
  • Add documentation: rewrite the API section of README.md; optionally add docs/api.md.
  • Ensure examples use realistic payloads.
  • Validate security assumptions: docs do not encourage shipping with auth disabled in production.
• Test and commit

Test and commit

• Run npm run build and npm test to confirm nothing breaks; run npm run lint.
• Verify every documented route actually exists in src/index.ts.
• Include a note in the PR confirming README/OpenAPI parity.

Example commit message

docs: document the full http api surface and align with openapi

Guidelines

• Minimum 95 percent test coverage for impacted modules (where tests are added).
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ 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.