PreviewDocs / Advanced Preview
defineRoute
Advanced preview: define focused HTTP routes with typed schemas, auth modes, and generated-client support.
Optional app integration
This surface is not part of the default agent path and does not make Auggy a general application backend. Its API may change before 1.0; pin exact versions and validate authorization and operational boundaries.
Shape
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.
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 routesAdvanced preview: expose focused HTTP behavior for frontends, webhooks, and server integrations without running a model turn.Connect an applicationAdvanced preview: generate a typed route client and call an augment route from a Next.js application.WebhooksAdvanced preview: handle provider callbacks through focused augment routes with deterministic signature checks.