# Add HTTP routes

Canonical: https://auggy.dev/docs/add-http-routes
Status: Preview
Package: auggy 0.5.0

Advanced preview: expose focused HTTP behavior for frontends, webhooks, and server integrations without running a model turn.

## When to add a route

> **Note: Optional advanced preview**
>
> A normal **Auggy** project does not need HTTP routes. Add one only when software already knows the exact operation it needs; use a tool when the model should mediate the operation during a turn.

- A browser, mobile app, server job, webhook, or outside service needs to call the capability directly.
- The behavior should be typed, repeatable, auditable, fast, or state-changing.
- A generated client should call the capability without hand-writing paths and auth headers.
- A chat-first flow needs a route-backed UI component to complete a structured action.

## Current route surface

- GET and POST routes.
- Exact paths and full-segment path params such as /orders/:id.
- Route groups, path params, query parsing, JSON body parsing, and response helpers.
- Zod schemas for params, query, body, and successful JSON responses.
- auth: none, bearer, creator, visitor.optional, visitor.required, or agent.required.
- Per-route body caps, timeouts, and rate limits.
- Route manifests, --json, --openapi, and generated TypeScript clients through `auggy routes`.
- Webhook signature policy metadata, with runtime Stripe and Svix verification.

## Route example

**Typed route**

```ts
import { defineRoute, json } from "auggy";
import { z } from "zod";

const SearchQuery = z.object({
  q: z.string().min(1),
});

export const routes = [
  defineRoute.get("/services/search", {
    auth: "none",
    query: SearchQuery,
    response: z.object({
      services: z.array(z.object({ id: z.string(), name: z.string() })),
    }),
    handler: async ({ query }) => {
      const services = await searchServices(query.q);
      return json({ services });
    },
  }),
];
```

## Route classes

| Route class | Examples | Typical auth |
| --- | --- | --- |
| Public discovery | GET /catalog/search, GET /services | none or visitor.optional |
| Lead and intake | POST /leads/create, POST /support/intake | none or visitor.optional |
| Draft state | POST /orders/draft, POST /appointments/hold | visitor.optional or visitor.required |
| Final handoff | POST /checkout/create, POST /bookings/:id/confirm | visitor.required |
| Account lookup | GET /orders/:id, GET /tickets/:id/status | visitor.required |
| Webhooks | POST /webhooks/stripe or /webhooks/agentmail | Stripe/Svix signature policy or handler-verified provider auth |
| Operator actions | POST /admin/reindex, POST /catalog/sync | bearer or creator |

## Related

- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [defineRoute](https://auggy.dev/docs/define-route/markdown)
- [Connect an application](https://auggy.dev/docs/connect-application/markdown)