Writing ryOS API Routes

ryOS API routes are Node-style handlers under api/, served by the standalone Bun server (scripts/api-standalone-server.ts). The canonical reference is docs/8.10-api-design-guide.md — read it for the full contract. This skill is the practical checklist.

Quick Start Checklist

- [ ] 1. Pick the path: api/<feature>/index.ts (collection) or api/<feature>/[id].ts (item)
- [ ] 2. Wrap the handler in apiHandler({ methods, auth, ... })
- [ ] 3. Validate input (Zod via bodySchema, or _utils/_validation.ts helpers)
- [ ] 4. Rate-limit public / expensive routes (_utils/_rate-limit.ts)
- [ ] 5. Use shared constants/keys (_utils/constants.ts, REDIS_PREFIXES)
- [ ] 6. Return explicit JSON; errors as { error: "..." }
- [ ] 7. Add structured logs (logger.info / branch decisions)
- [ ] 8. Write/extend an integration test in tests/ (requires `bun run dev:api`)
- [ ] 9. Update the matching docs/8.*.md if the contract changed

File & Naming Conventions