# API Add Route

> Use when adding or changing an HTTP route under services/api. Walks the exact steps so the new route follows Helpline's gateway conventions.

- Skill: `coleam00/api-add-route` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add coleam00/api-add-route`
- Raw SKILL.md: https://api.skillmd.com/api/skills/coleam00/api-add-route/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: coleam00 (https://skillmd.com/u/coleam00)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/coleam00/api-add-route

---


# Adding an API route

Activates for work in `services/api`. Follow these steps in order.

1. **Write the handler** in the matching module (`tickets.py` for ticket
   routes, a new module for a new noun). Signature is
   `(request: dict) -> dict`.
2. **Validate inputs first.** Missing/!bad input raises `ValidationError` —
   never return an error dict by hand.
3. **Do no business logic here.** Call a repo (`packages/db`) or another
   service. The handler only orchestrates and shapes the response.
4. **Register the route** in `routes.py` inside `build_app()` —
   `app.route("METHOD /path", handler)`. A route not registered there does not
   exist.
5. **Add a test** in `tests/` that builds the app and dispatches the route.

Full checklist with a worked example: [references/route-checklist.md](references/route-checklist.md).