docs: API reference (REST + GraphQL)

[Omoboi-dev]

Context
Developers need a reference for the endpoints Stardex exposes.

Task
Document the REST endpoints and the GraphQL schema, with request/response
examples.

Pointers

• Add to docs/; keep it in sync with api/.
• Depends on the relevant endpoints existing.

Acceptance criteria

• Each endpoint/field documented with examples
• Linked from README

Notes
🟢 Good first issue (best done as endpoints stabilize).