HTTP API

Confect’s HTTP integration mounts an Effect HTTP router onto Convex: you register routes with Effect’s effect/unstable/http and effect/unstable/httpapi modules—HttpApi endpoints, plain routes, interactive Scalar docs, middleware—and Confect serves them from a single Convex HTTP action, supplying its services to your handlers on every request.

Defining an API

Define API groups and endpoints using effect/unstable/httpapi, implement the endpoint handlers with HttpApiBuilder.group, and export a layer that registers the API’s routes. Handlers have access to the Confect services available in the HTTP action context. Endpoint paths are absolute; place an API under a path prefix with .prefix(...).

confect/http/NotesApi.ts

import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Schema from "effect/Schema";
import * as HttpApi from "effect/unstable/httpapi/HttpApi";
import * as HttpApiBuilder from "effect/unstable/httpapi/HttpApiBuilder";
import * as HttpApiEndpoint from "effect/unstable/httpapi/HttpApiEndpoint";
import * as HttpApiGroup from "effect/unstable/httpapi/HttpApiGroup";
import * as OpenApi from "effect/unstable/httpapi/OpenApi";
import refs from "../_generated/refs";
import { QueryRunner } from "../_generated/services";
import notes from "../_generated/tables/notes";

class ApiGroup extends HttpApiGroup.make("notes")
  .add(
    HttpApiEndpoint.get("getFirst", "/get-first", {
      success: Schema.OptionFromNullOr(notes.Doc),
    }).annotate(OpenApi.Description, "Get the first note, if there is one."),
  )
  .annotate(OpenApi.Title, "Notes")
  .annotate(OpenApi.Description, "Operations on notes.") {}

export class Api extends HttpApi.make("Api")
  .annotate(OpenApi.Title, "Confect Example")
  .add(ApiGroup)
  .prefix("/path-prefix") {}

const ApiLive = HttpApiBuilder.group(Api, "notes", (handlers) =>
  handlers.handle("getFirst", () =>
    Effect.gen(function* () {
      const runQuery = yield* QueryRunner;

      const firstNote = yield* runQuery(
        refs.public.notes_and_random.notes.getFirst,
        {},
      );

      return firstNote;
    }).pipe(Effect.orDie),
  ),
);

/**
 * Registers {@link Api}'s routes, with its group handlers provided.
 */
export const layer = HttpApiBuilder.layer(Api).pipe(Layer.provide(ApiLive));

HttpApiBuilder.layer(Api) registers the API’s routes; Layer.provide(ApiLive) supplies its group handlers. Forgetting a group is a compile-time error—the unprovided group requirement is rejected where the layer is mounted.

API documentation

HttpApiScalar.layer serves interactive docs, powered by Scalar and generated from your endpoint definitions and OpenApi annotations. Set baseServerURL to your deployment’s site URL so the docs page’s “try it” requests target the right host—Confect installs a Convex-aware ConfigProvider, so Config reads (in layer construction, route handlers, and middleware alike) resolve against your Convex environment variables.

confect/http/ScalarDocs.ts

import * as Config from "effect/Config";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as HttpApiScalar from "effect/unstable/httpapi/HttpApiScalar";
import { Api } from "./NotesApi";

/**
 * Serves interactive API documentation for {@link Api}, powered by
 * [Scalar](https://github.com/scalar/scalar).
 */
export const layer = Layer.unwrap(
  Effect.gen(function* () {
    const siteUrl = yield* Effect.orDie(Config.string("CONVEX_SITE_URL"));

    return HttpApiScalar.layer(Api, {
      path: "/path-prefix/docs",
      scalar: { baseServerURL: siteUrl },
    });
  }),
);

Creating the router

Create the Convex HTTP router in confect/http.ts with HttpRouter.make from @confect/server. It takes a single Layer that registers your routes—merge your API and docs layers with any other building blocks from Effect’s effect/unstable/http:

HttpRouter.add(method, path, handler) registers a plain route.
HttpRouter.middleware(fn, { global: true }) applies middleware to every route.

Confect’s HttpRouter module collides with Effect’s, so alias it on import:

confect/http.ts

import { HttpRouter as ConfectHttpRouter } from "@confect/server";
import { flow } from "effect/Function";
import * as Layer from "effect/Layer";
import * as HttpMiddleware from "effect/unstable/http/HttpMiddleware";
import * as HttpRouter from "effect/unstable/http/HttpRouter";
import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
import * as NotesApi from "./http/NotesApi";
import * as ScalarDocs from "./http/ScalarDocs";

export default ConfectHttpRouter.make(
  Layer.mergeAll(
    NotesApi.layer,
    ScalarDocs.layer,
    HttpRouter.add("GET", "/health", HttpServerResponse.text("OK")),
    HttpRouter.middleware(flow(HttpMiddleware.cors(), HttpMiddleware.logger), {
      global: true,
    }),
  ),
);

Routing semantics

HttpRouter.make registers a single catch-all Convex HTTP action under the path prefix /, so the Effect router is the single source of truth for paths:

Any number of HttpApi definitions, docs pages, and plain routes can be merged onto the one router.
Requests that match no Effect route receive the Effect router’s 404 response.
Plain Convex routes still work: add them to the returned router with .route(...). Convex matches exact paths first and longer path prefixes before the catch-all, so they take precedence over the Effect router.

confect/http.ts (continued)

import { httpActionGeneric } from "convex/server";

const http = ConfectHttpRouter.make(/* ... */);

http.route({
  path: "/plain-convex",
  method: "GET",
  handler: httpActionGeneric(() => Promise.resolve(new Response("ok"))),
});

export default http;

Getting Started

Concepts

Server

Clients

Guides

Defining an API

API documentation

Creating the router

Routing semantics

​Defining an API

​API documentation

​Creating the router

​Routing semantics

Defining an API

API documentation

Creating the router

Routing semantics