Convex HTTP actions

Convex HTTP actions

Defines public HTTP endpoints served from the deployment's .convex.site domain. The one rule: an httpAction handler treats every byte of the request as untrusted, verifies it, then calls internal.* functions with ctx.runQuery or ctx.runMutation. It never reads or writes ctx.db directly.

When to reach for this

• A third party (Stripe, Clerk, Resend, GitHub) needs a URL to POST events to
• A client without the Convex SDK (mobile app, CLI, another backend) needs a plain HTTP API
• A browser needs to download or stream bytes without going through useQuery
• A script or form needs to upload bytes over HTTP instead of an upload URL

httpAction or mutation

HTTP actions get no argument validators and no automatic auth. They run in the default Convex runtime, so Web APIs (fetch, crypto.subtle, Response, ReadableStream) work without "use node". Request and response bodies are capped at 20MB.

Router skeleton

The router must live at convex/http.ts and be the default export. A router in any other file is ignored.

// convex/http.ts
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { internal } from "./_generated/api";

const http = httpRouter();

http.route({
  path: "/api/items",
  method: "POST",
  handler: httpAction(async (ctx, request) => {
    let body: { name?: unknown };
    try {