# defineRoute

Canonical: https://auggy.dev/docs/define-route
Status: Preview
Package: auggy 0.5.0

Advanced preview: define focused HTTP routes with typed schemas, auth modes, and generated-client support.

## Shape

> **Note: Optional app-integration API**
>
> defineRoute is not required to build an **Auggy** agent. Use it for a focused deterministic integration, not as a replacement for a general application backend.

**Route definition**

```ts
defineRoute.post("/orders/:id/refund", {
  auth: "visitor.required",
  params: z.object({ id: z.string() }),
  body: z.object({ reason: z.string() }),
  maxBodyBytes: 8192,
  rateLimit: { maxPerMinute: 5 },
  requires: { action: "refund.issue", resource: { param: "id" } },
  response: z.object({ refundId: z.string(), orderId: z.string() }),
  handler: async ({ params, body }) => {
    return json(await refundOrder(params.id, body.reason));
  },
});
```

defineRoute.get and defineRoute.post are the supported methods. Paths take exact segments and full-segment params such as /orders/:id.

## Options

| Option | Use |
| --- | --- |
| auth | One of none, bearer, creator, visitor.optional, visitor.required, or agent.required. |
| params, query, body | Zod schemas; parsed and validated before the handler runs. |
| response | Zod schema for the success JSON body; types the generated client's data. |
| maxBodyBytes | Per-route request body cap. |
| rateLimit | { maxPerMinute } per-route rate limit. |
| timeoutMs | Per-route handler timeout. |
| policy | Webhook policy metadata, such as webhook.signature("stripe", { secretEnv }) or webhook.signature("svix", { secretEnv }). |
| requires | Delegated authorization rule: { action, resource: { param } }. |
| handler | Receives parsed { params, query, body, request } and returns a Response; `json()` is the standard helper. |

## Auth modes

| Mode | Use |
| --- | --- |
| none | Public routes. |
| bearer | Trusted server or operator callers with bearer credentials. |
| creator | Creator-only maintenance and back-office actions. |
| visitor.optional | Public routes that can enrich behavior when a visitor token is present. |
| visitor.required | Private visitor routes that require verified visitor identity. |
| agent.required | Admitted agent callers. |

## Related

- [Add HTTP routes](https://auggy.dev/docs/add-http-routes/markdown)
- [Connect an application](https://auggy.dev/docs/connect-application/markdown)
- [Webhooks](https://auggy.dev/docs/webhooks/markdown)