--- title: "nuxt-backend/http" description: "Every export of nuxt-backend/http, with its signature and where it is defined." canonical_url: "https://nuxt-backend.dev/docs/reference/api/http" --- # nuxt-backend/http ## Interfaces ### RegisterBackendRoutesOptions Defined in: [src/convex/integrations/http.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/http.ts) One call to mount every inbound route the backend handles on your Convex HTTP router: the auth routes, the agent (MCP) token exchange, the guarded billing events endpoint (entitlement refresh + gift fulfilment), the guarded email delivery-events endpoint (status tracking), and the metered AI stream endpoint. Each part is required: a route left unmounted fails only when a provider or a client first calls it. The webhook endpoints share one fail-closed policy (see `webhook-guard.ts`): missing secret → 503, invalid signature → 403 (±5 min replay tolerance), oversized → 413, authentic-but-unknown type → 202, handler throw → 500 so the provider retries, redelivery of a processed id → 200. Every request's outcome lands in the component's delivery log. #### Properties
Property Type Description Defined in
auth { authComponent : { registerRoutes : (... args ) => void ; }; createAuth : unknown ; mcp : { exchangeHandler : ( ctx , request ) => Promise < Response >; }; } From setupAuth : mounts the auth HTTP routes, and the agent token exchange (its mcp export) at RegisterBackendRoutesOptions.mcpExchangePath , where the Nuxt MCP gate trades agents' OAuth Bearers for short-lived Convex JWTs. src/convex/integrations/http.ts
auth.authComponent { registerRoutes : (... args ) => void ; } - src/convex/integrations/http.ts
auth.authComponent.registerRoutes (... args ) => void - src/convex/integrations/http.ts
auth.createAuth unknown - src/convex/integrations/http.ts
auth.mcp { exchangeHandler : ( ctx , request ) => Promise < Response >; } - src/convex/integrations/http.ts
auth.mcp.exchangeHandler ( ctx , request ) => Promise < Response > - src/convex/integrations/http.ts
billing { webhookHandler : ( ctx , request ) => Promise < Response >; } From setupBilling : mounts the guarded billing events webhook at RegisterBackendRoutesOptions.billingPath (fail-closed statuses, redelivery dedupe, delivery logging — pass the whole billing instance). src/convex/integrations/http.ts
billing.webhookHandler ( ctx , request ) => Promise < Response > - src/convex/integrations/http.ts
email { webhookHandler : ( ctx , request ) => Promise < Response >; } From setupEmail : mounts the email events webhook at RegisterBackendRoutesOptions.emailPath . src/convex/integrations/http.ts
email.webhookHandler ( ctx , request ) => Promise < Response > - src/convex/integrations/http.ts
ai { httpHandler : unknown ; corsOrigin : string ; } From setupAi : mounts the metered stream endpoint at RegisterBackendRoutesOptions.aiPath . src/convex/integrations/http.ts
ai.httpHandler unknown - src/convex/integrations/http.ts
ai.corsOrigin string - src/convex/integrations/http.ts
billingPath? string Route for the billing events webhook. Default /billing/events . src/convex/integrations/http.ts
emailPath? string Route for the email events webhook. Default /email/events . src/convex/integrations/http.ts
aiPath? string Route for the AI stream endpoint. Default /ai/stream . src/convex/integrations/http.ts
mcpExchangePath? string Route for the agent token exchange. Default /mcp/exchange . src/convex/integrations/http.ts
## Functions ### registerBackendRoutes() ```ts function registerBackendRoutes(http, options): void; ``` Defined in: [src/convex/integrations/http.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/http.ts) #### Parameters
Parameter Type
http HttpRouter
options RegisterBackendRoutesOptions
#### Returns `void` #### Example ```ts // convex/http.ts import { registerBackendRoutes } from 'nuxt-backend/http' import { httpRouter } from 'convex/server' import { components } from './_generated/api' import { ai } from './ai' import { authComponent, createAuth, mcp } from './auth' import { billing } from './billing' import { email } from './email' const http = httpRouter() registerBackendRoutes(http, { auth: { authComponent, createAuth, mcp }, billing, email, ai }) export default http ``` ## Sitemap See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.