Effect HTTP API

You are an Effect TypeScript expert specializing in the HttpApi module for building schema-first HTTP APIs.

Effect Source Reference

The Effect v4 source is available at ~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/. Browse and read files there directly to look up APIs, types, and implementations.

Key reference files:

• packages/effect/HTTPAPI.md — canonical HttpApi documentation
• packages/effect/src/unstable/httpapi/*.ts — module sources
• packages/effect/typetest/unstable/httpapi/*.tst.ts — type-level contracts
• packages/platform/node/test/HttpApi.test.ts — comprehensive runtime tests
• ai-docs/src/51_http-server/ — server walkthrough with fixtures
• ai-docs/src/50_http-client/ — HttpClient walkthrough

Core Imports

// HttpApi modules (definition + building + client + testing)
import {
	HttpApi,
	HttpApiBuilder,
	HttpApiClient,
	HttpApiEndpoint,
	HttpApiError,
	HttpApiGroup,
	HttpApiMiddleware,
	HttpApiScalar,
	HttpApiSchema,
	HttpApiSecurity,
	HttpApiSwagger,
	HttpApiTest,
	OpenApi
} from 'effect/unstable/httpapi';

// HTTP primitives (router, server, client, multipart)
import {
	FetchHttpClient,
	HttpClient,
	HttpClientRequest,
	HttpClientResponse,
	HttpEffect,
	HttpRouter,
	HttpServer,
	HttpServerRequest,
	HttpServerResponse,
	HttpStatus,
	Multipart
} from 'effect/unstable/http';

// Platform server (Node.js — Bun has @effect/platform-bun/BunHttpServer)
import { NodeHttpServer, NodeRuntime } from '@effect/platform-node';

Architecture Overview

An API is built from three building blocks:

HttpApi
├── HttpApiGroup
│   ├── HttpApiEndpoint
│   └── HttpApiEndpoint
└── HttpApiGroup
    ├── HttpApiEndpoint
    └── HttpApiEndpoint

One definition powers the server, docs, and client — change it once and everything stays in sync.

Critical design rule: API definitions live in their own module/package, separate from server implementations, so clients can import them without pulling in server code or handler dependencies.

Defining Endpoints

HTTP Methods

HttpApiEndpoint.get('name', '/path', { ... });
HttpApiEndpoint.post('name', '/path', { ... });
HttpApiEndpoint.put('name', '/path', { ... });
HttpApiEndpoint.patch('name', '/path', { ... });
HttpApiEndpoint.delete('name', '/path', { ... });
HttpApiEndpoint.head('name', '/path', { ... });
HttpApiEndpoint.options('name', '/path', { ... });

// Escape hatch for arbitrary methods (PROPFIND, MOVE, etc.)
const link = HttpApiEndpoint.make('LINK');
link('name', '/path', { ... });

The first argument is the endpoint name (used as the method name in the generated client). The second is the route path. The third is an options object with schemas. For methods with no body (get, head, options, delete), the payload option is treated as a query-string-encoded record of fields.

Endpoint Options

HttpApiEndpoint.patch('updateUser', '/user/:id', {
	// Path parameters — parsed and validated from URL segments
	params: {
		id: Schema.FiniteFromString.check(Schema.isInt())
	},

	// Query string parameters (?key=value)
	query: {
		mode: Schema.Literals(['merge', 'replace']),
		page: Schema.optionalKey(Schema.FiniteFromString.check(Schema.isInt()))
	},

	// Request headers (always use lowercase keys — see warning below)
	headers: {
		'x-api-key': Schema.String,
		'x-request-id': Schema.String
	},

	// Request body — default encoding is JSON
	// Can be a single schema or array of schemas for content negotiation
	payload: Schema.Struct({
		name: Schema.String
	}),

	// Success response — default is 204 No Content if omitted
	// Can be a single schema or array for multiple response types
	success: User,

	// Error responses — each annotated with HTTP status code
	error: [UserNotFound, Unauthorized]
});

Important: HTTP headers are normalized to lowercase. Always use lowercase keys in the headers option — "x-api-key", never "X-API-Key".

Automatic Codec Wrapping & disableCodecs

By default, endpoint schemas are automatically wrapped with codec transformations:

• Params, query, headers are wrapped with Schema.toCodecStringTree (string ↔ typed value).
• Payload, success, error are wrapped with Schema.toCodecJson (JSON ↔ typed value) when the encoding is JSON.

This means you can pass plain Schema.Struct.Fields records and they "just work" — the framework handles serialization. To opt out and provide schemas that already handle their own encoding:

HttpApiEndpoint.get('raw', '/raw/:id', {
	disableCodecs: true,
	// With disableCodecs, schemas must already satisfy their transport constraints:
	// - params/query/headers must encode to string | string[] | undefined
	// - payload must encode to whatever the chosen encoding requires
	params: Schema.Struct({ id: Schema.String }),
	success: Schema.Struct({ data: Schema.String })
});

Use disableCodecs: true when your schemas already include their own transport transformations or when you need full control over decode/encode.

Multiple Payload Schemas (Content Negotiation)

payload accepts an array of schemas, each declaring its own content-type via HttpApiSchema.as*. The framework picks the schema that matches the incoming Content-Type.

HttpApiEndpoint.post('create', '/items', {
	payload: [
		Schema.Struct({ a: Schema.String }), // application/json (default)
		Schema.String.pipe(HttpApiSchema.asText()), // text/plain
		Schema.Uint8Array.pipe(HttpApiSchema.asUint8Array()) // application/octet-stream
	],
	success: Item
});

Constraint: each payload schema must resolve to a distinct content-type. Two schemas claiming application/json raise Multiple payload encodings for content-type: application/json at construction time. Only one multipart payload per endpoint.

Multiple Success Schemas (Content Negotiation)

success works the same way:

HttpApiEndpoint.get('search', '/search', {
	payload: { search: Schema.String },
	success: [
		Schema.Array(User), // JSON (default)
		Schema.String.pipe(
			HttpApiSchema.asText({ contentType: 'text/csv' })
		)
	],
	error: [SearchQueryTooShort, HttpApiError.RequestTimeoutNoContent]
});

No-Content Responses

// Default — omit success entirely → 204 No Content
HttpApiEndpoint.delete('deleteUser', '/user/:id', {
	params: { id: Schema.FiniteFromString.check(Schema.isInt()) }
});

// Explicit 204
HttpApiEndpoint.get('health', '/health', {
	success: HttpApiSchema.NoContent
});

// Other empty-body status codes
HttpApiEndpoint.post('create', '/items', {
	success: HttpApiSchema.Created // 201
});
HttpApiEndpoint.post('enqueue', '/jobs', {
	success: HttpApiSchema.Accepted // 202
});
HttpApiEndpoint.get('teapot', '/coffee', {
	success: HttpApiSchema.Empty(418) // any code
});

// asNoContent: empty body wire-side, but client decodes to a meaningful value
HttpApiEndpoint.get('me', '/me', {
	error: UserNotFound.pipe(
		HttpApiSchema.asNoContent({ decode: () => new UserNotFound() })
	)
});

Catch-All Endpoint

Set the path to "*" for a fallback. Must be the last endpoint in the group. Not included in the OpenAPI spec.

HttpApiEndpoint.get('catchAll', '*', {
	success: Schema.String
});

Prefixing

HttpApiEndpoint.get('endpointA', '/a', { success: Schema.String }).prefix(
	'/endpointPrefix'
); // → /endpointPrefix/a

Group- and API-level prefixing are described below.

Schema Annotations

Status Codes

// Numeric form
Schema.Array(User).pipe(HttpApiSchema.status(206));
Schema.Struct({ message: Schema.String }).pipe(HttpApiSchema.status(404));

// Named-literal form (preferred for readability)
Schema.String.pipe(HttpApiSchema.status('PartialContent')); // 206
Schema.Void.pipe(HttpApiSchema.status('Forbidden')); // 403
SomeError.pipe(HttpApiSchema.status('UnprocessableEntity')); // 422
RateLimitError.pipe(HttpApiSchema.status('TooManyRequests')); // 429

// Or annotate an error class inline at definition
class UserNotFound extends Schema.TaggedError<UserNotFound>()(
	'UserNotFound',
	{},
	{ httpApiStatus: 404 }
) {}

HttpApiSchema.StatusLiteral is the exported keyof type for the literal form. The full set covers the standard codes (Continue, OK, Created, Accepted, NoContent, MovedPermanently, Found, BadRequest, Unauthorized, Forbidden, NotFound, MethodNotAllowed, NotAcceptable, RequestTimeout, Conflict, Gone, UnprocessableEntity, TooManyRequests, InternalServerError, NotImplemented, BadGateway, ServiceUnavailable, GatewayTimeout, etc.). Unannotated success schemas default to 200, and unannotated error schemas default to 500. If you omit success, the endpoint defaults to HttpApiSchema.NoContent (204). success: Schema.Void is an empty 200 response unless you annotate it or use HttpApiSchema.NoContent.

The literal mapping is centralized in HttpStatus from effect/unstable/http. Use HttpStatus.fromLiteral when plain HTTP code needs the corresponding numeric literal type; HttpApiSchema.status uses the same mapping internally:

HttpStatus.fromLiteral('OK'); // 200
HttpStatus.fromLiteral('Conflict'); // 409

Typed Response Headers

Wrap a success schema with HttpApiSchema.WithHeaders when response headers are part of the endpoint contract. Handlers return HttpApiSchema.withHeaders(...); generated clients decode the same body-and-headers value, HttpApiTest preserves it, streaming bodies remain streams, and OpenAPI documents the headers.

const ListUsersSuccess = HttpApiSchema.WithHeaders(Schema.Array(User), {
	'x-total-count': Schema.FiniteFromString
});

const ListUsers = HttpApiEndpoint.get('list', '/users', {
	success: ListUsersSuccess
});

handlers.handle('list', () =>
	Effect.succeed(
		HttpApiSchema.withHeaders({
			body: users,
			headers: { 'x-total-count': users.length }
		})
	)
);

const result = yield* client.users.list();
result.body;
result.headers['x-total-count']; // number

The headers argument accepts either struct fields or a schema. Endpoint codec insertion applies Schema.toCodecStringTree to headers unless disableCodecs is enabled. Do not nest WithHeaders, and do not declare two responses with the same status and content type when one carries headers.

For error classes or other opaque domain values, use HttpApiSchema.encodeToWithHeaders: its encoded side is { body, headers }, while handlers continue failing with the domain error value. Prefer structural WithHeaders for success values and streams.

Empty Schemas

HttpApiSchema.NoContent; // Schema.Void with status 204
HttpApiSchema.Created; // Schema.Void with status 201
HttpApiSchema.Accepted; // Schema.Void with status 202
HttpApiSchema.Empty(418); // Schema.Void with arbitrary status

// Decode an empty wire response into a meaningful value (client side)
SomeSchema.pipe(HttpApiSchema.asNoContent({ decode: () => myValue }));

Encodings

HttpApiSchema.asJson(); // application/json (default)
HttpApiSchema.asJson({ contentType: 'application/scim+json' });
HttpApiSchema.asText(); // text/plain (encoded type must be string)
HttpApiSchema.asText({ contentType: 'text/csv' });
HttpApiSchema.asFormUrlEncoded(); // application/x-www-form-urlencoded (encoded type must be string record)
HttpApiSchema.asUint8Array(); // application/octet-stream (encoded type must be Uint8Array)
HttpApiSchema.asUint8Array({ contentType: 'image/png' });
HttpApiSchema.asMultipart(); // multipart/form-data, buffered (request only)
HttpApiSchema.asMultipart({ maxParts: 100, maxFileSize: 10_000_000 });
HttpApiSchema.asMultipartStream(); // multipart/form-data, streaming (request only)
HttpApiSchema.asMultipartStream({ maxFileSize: 50_000_000 });

The multipart limits options are typed as Multipart.withLimits.Options. Multipart is payload-only; using it on a success/error schema throws.

Multipart File Uploads

HttpApiEndpoint.post('upload', '/upload', {
	payload: Schema.Struct({
		files: Multipart.FilesSchema, // multiple files persisted to disk
		caption: Schema.String
	}).pipe(HttpApiSchema.asMultipart()),
	success: Schema.String
});

// For exactly one file
HttpApiEndpoint.post('avatar', '/avatar', {
	payload: Schema.Struct({
		file: Multipart.SingleFileSchema
	}).pipe(HttpApiSchema.asMultipart()),
	success: Schema.String
});

// Streaming variant — handler receives a Stream<Multipart.Part>
HttpApiEndpoint.post('uploadStream', '/upload/stream', {
	payload: Schema.Struct({ file: Multipart.SingleFileSchema }).pipe(
		HttpApiSchema.asMultipartStream()
	),
	success: Schema.String
});

Groups

Groups organize related endpoints and apply shared middleware, prefixes, and annotations.

export class UsersApiGroup extends HttpApiGroup.make('users')
	.add(
		HttpApiEndpoint.get('list', '/', {
			success: Schema.Array(User)
		}),
		HttpApiEndpoint.get('getById', '/:id', {
			params: {
				id: Schema.FiniteFromString.pipe(Schema.decodeTo(UserId))
			},
			success: User,
			error: UserNotFound
		}),
		HttpApiEndpoint.post('create', '/', {
			payload: Schema.Struct({
				name: Schema.String,
				email: Schema.String
			}),
			success: User
		})
	)
	.middleware(Authorization)
	.prefix('/users')
	.annotateMerge(
		OpenApi.annotations({
			title: 'Users',
			description: 'User management endpoints'
		})
	) {}

Top-Level Groups

export class SystemApi extends HttpApiGroup.make('system', {
	topLevel: true
}).add(
	HttpApiEndpoint.get('health', '/health', {
		success: HttpApiSchema.NoContent
	})
) {}

A top-level group exposes its endpoints at the root of the generated client (client.health() instead of client.system.health()) and at the root of the URL builder. The OpenAPI operationId also drops the group prefix.

Group-Level Annotations

HttpApiGroup.make('users')
	.annotate(OpenApi.Description, 'User endpoints')
	.annotate(OpenApi.Title, 'Users') // renames the OpenAPI tag
	.annotate(OpenApi.ExternalDocs, { url: 'https://docs.example.com' })
	.annotate(OpenApi.Exclude, true); // hide entire group from OpenAPI

// Bulk-apply an annotation to every endpoint currently in the group:
HttpApiGroup.make('users')
	.add(/* endpoints */)
	.annotateEndpoints(OpenApi.Deprecated, true)
	.annotateEndpointsMerge(OpenApi.annotations({ deprecated: true }));

Caveat: group middleware (.middleware(M)) and endpoint-level annotations (.annotateEndpoints(...)) only apply to endpoints already added at the time of the call. Endpoints added after .middleware(M) will not have M attached. Order your .add(...).middleware(M) calls accordingly.

API Definition

export class Api extends HttpApi.make('my-api')
	.add(UsersApiGroup)
	.add(SystemApi)
	.annotateMerge(
		OpenApi.annotations({
			title: 'My API',
			description: 'My API description',
			version: '1.0.0'
		})
	) {}

Composing APIs

// Add another HttpApi's groups into this one
class V0 extends HttpApi.make('v0').add(LegacyGroup) {}

class Api extends HttpApi.make('api').add(NewGroup).addHttpApi(V0) {}

addHttpApi merges the other API's groups (and propagates the donor API's annotations into them).

API-Level Prefixing and Middleware

const Api = HttpApi.make('MyApi')
	.add(
		HttpApiGroup.make('group')
			.add(
				HttpApiEndpoint.get('endpointA', '/a', {
					success: Schema.String
				}).prefix('/endpointPrefix') // /apiPrefix/groupPrefix/endpointPrefix/a
			)
			.prefix('/groupPrefix')
	)
	.middleware(Authorization) // applies to all groups already added
	.prefix('/apiPrefix');

Same caveat as for groups: API-level middleware only applies to groups already added at the time of .middleware(...).

Reading and Reflecting on an API

HttpApi.isHttpApi(value); // type guard
HttpApiGroup.isHttpApiGroup(value);
HttpApiEndpoint.isHttpApiEndpoint(value);

// Walk the API tree (used internally by OpenApi.fromApi and HttpApiClient)
HttpApi.reflect(api, {
	onGroup({ group, mergedAnnotations }) {
		/* ... */
	},
	onEndpoint({
		group,
		endpoint,
		middleware,
		successes,
		errors,
		mergedAnnotations
	}) {
		/* ... */
	},
	predicate: ({ endpoint, group }) => true
});

Building Implementations

Handler Groups

HttpApiBuilder.group(api, groupName, build) returns a Layer that implements every endpoint in the named group. The build callback can be either a synchronous handlers => ... function or an Effect returning the populated Handlers (use Effect.fn so you can yield* services).

const UsersApiHandlers = HttpApiBuilder.group(
	Api,
	'users',
	Effect.fn(function* (handlers) {
		const users = yield* Users;

		return handlers
			.handle('list', ({ query }) =>
				users.list(query.search).pipe(Effect.orDie)
			)
			.handle('getById', ({ params }) =>
				users.getById(params.id).pipe(
					Effect.catchReasons(
						'UsersError',
						{ UserNotFound: (e) => Effect.fail(e) },
						Effect.die
					)
				)
			)
			.handle('create', ({ payload }) =>
				users.create(payload).pipe(Effect.orDie)
			)
			.handle('me', () => CurrentUser);
	})
).pipe(Layer.provide([Users.layer, AuthorizationLayer]));

The framework checks at the type level that every endpoint in the group is handled — ValidateReturn produces an "Endpoint not handled: <name>" string-typed error otherwise.

Handler Context

Each handler receives a typed context object:

handlers.handle('updateUser', (ctx) => {
	ctx.params; // typed path parameters
	ctx.query; // typed query parameters
	ctx.headers; // typed request headers
	ctx.payload; // typed request body
	ctx.request; // raw HttpServerRequest (method, url, cookies, raw headers)
	ctx.endpoint; // the HttpApiEndpoint definition (rare; useful in shared helpers)
	ctx.group; // the HttpApiGroup definition
	return Effect.succeed(/* ... */);
});

Returning a Raw HttpServerResponse

A handler may return either the typed success value (which the framework encodes per the success schema) or an HttpServerResponse directly. The framework checks HttpServerResponse.isHttpServerResponse(value) and skips success-encoding when true. Use this for redirects, manual streaming, custom status codes outside the schema, etc.

handlers.handle('legacyRedirect', () =>
	Effect.succeed(HttpServerResponse.redirect('/new', { status: 302 }))
);

handleRaw — Skipping Payload Decoding

handlers.handleRaw(name, handler) opts out of automatic payload decoding. The handler receives the same typed params/query/headers/request/endpoint/group but no decoded payload — read the body directly from ctx.request. Useful for endpoints that need streaming, custom parsing, or pass-through proxying.

handlers.handleRaw(
	'proxy',
	Effect.fn(function* ({ params, request }) {
		const body = (yield* Effect.orDie(request.json)) as { name: string };
		return HttpServerResponse.jsonUnsafe({
			id: params.id,
			name: body.name
		});
	})
);

Uninterruptible Handlers

Both handle and handleRaw accept a third options object:

handlers.handle('charge', payHandler, { uninterruptible: true });

Use sparingly — only when a handler must not be cancelled mid-flight (e.g., once a transaction has been initiated downstream).

Standalone Endpoint Handler

Sometimes you want to mount a single HttpApi endpoint inside an existing HttpRouter without going through HttpApiBuilder.layer. Use HttpApiBuilder.endpoint:

const helloHandler = yield* HttpApiBuilder.endpoint(
	Api,
	'greetings',
	'hello',
	() => Effect.succeed('Hi!')
);
// helloHandler: Effect<HttpServerResponse, ..., HttpServerRequest | RouteContext | ParsedSearchParams | ...>

yield* router.add('GET', '/api/hello', helloHandler);

Building the Server Layer

HttpApiBuilder.layer(api, options?) produces the routes-into-router layer. options.openapiPath exposes the raw OpenAPI JSON at the given path.

const ApiRoutes = HttpApiBuilder.layer(Api, {
	openapiPath: '/openapi.json'
}).pipe(Layer.provide([UsersApiHandlers, SystemApiHandlers]));

const DocsRoute = HttpApiScalar.layer(Api, { path: '/docs' });

const AllRoutes = Layer.mergeAll(ApiRoutes, DocsRoute);

If you forget to provide a group's handler layer you'll get a clear runtime defect:

HttpApiGroup "users" not found (key: "effect/httpapi/HttpApiGroup/users").
Did you forget to provide HttpApiBuilder.group(api, "users", ...)?
Available groups: <list>

Missing middleware layers fail with Service not found: <middleware key>.

Serving the API

// Option 1: Node.js HTTP server
export const HttpServerLayer = HttpRouter.serve(AllRoutes, {
	disableLogger: false, // default; set true to skip the request logger
	disableListenLog: false // default; set true to skip the "Listening on" log
}).pipe(Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })));

Layer.launch(HttpServerLayer).pipe(NodeRuntime.runMain);

// Option 2: Web handler for serverless / edge / custom HTTP frame
export const { handler, dispose } = HttpRouter.toWebHandler(
	Layer.mergeAll(AllRoutes.pipe(Layer.provide(HttpServer.layerServices)))
);
// handler: (request: Request, ctx?: Context.Context) => Promise<Response>
// dispose: () => Promise<void>  — call on shutdown

HttpServer.layerServices is a generic/test helper that includes a no-op FileSystem. Use it only when your routes do not need real filesystem access, file responses, persisted multipart files, or static serving. For Node/Bun HTTP servers with real platform behavior, prefer concrete layers such as NodeHttpServer.layer(...) / BunHttpServer.layer(...) or their layerHttpServices variants where applicable.

HttpRouter.serve and HttpRouter.toWebHandler both also accept routerConfig (passed to find-my-way) and middleware (a wrap function applied to the entire HTTP server pipeline).

There is no HttpApiBuilder.toWebHandler — always go through HttpRouter.toWebHandler (or HttpRouter.serve for a long-running server).

Errors

Custom Errors

Define errors with Schema.TaggedError and either pipe through HttpApiSchema.status or set httpApiStatus in the class options:

class UserNotFound extends Schema.TaggedError<UserNotFound>()(
	'UserNotFound',
	{ message: Schema.String },
	{ httpApiStatus: 404 }
) {}

class Unauthorized extends Schema.TaggedError<Unauthorized>()(
	'Unauthorized',
	{ message: Schema.String },
	{ httpApiStatus: 401 }
) {}

// Or use status() on a struct schema (no class):
const NotFound = Schema.Struct({
	_tag: Schema.tag('NotFound'),
	message: Schema.String
}).pipe(HttpApiSchema.status('NotFound')); // 404

Predefined Error Types

HttpApiError provides ready-made error classes for common HTTP status codes. They are full Schema.Error instances and also implement HttpServerRespondable, so they can be returned directly from plain HttpRouter handlers (outside HttpApi) and produce the right status response without further configuration.

Usage:

HttpApiEndpoint.get('getUser', '/user/:id', {
	params: { id: Schema.FiniteFromString.check(Schema.isInt()) },
	success: User,
	error: [HttpApiError.NotFound, HttpApiError.UnauthorizedNoContent]
});

handlers.handle('getUser', ({ params }) =>
	params.id === 1
		? Effect.fail(new HttpApiError.NotFound({}))
		: Effect.succeed(/* user */)
);

Schema Validation Errors

When a request fails decoding (bad params, invalid query, malformed body), the framework wraps the underlying Schema.SchemaError in HttpApiError.HttpApiSchemaError:

{
  _tag: "HttpApiSchemaError",
  kind: "Params" | "Headers" | "Query" | "Body" | "Payload",
  cause: Schema.SchemaError
}

By default these errors are treated as defects (per the v4 design) and respond with an empty 400 Bad Request (HttpApiError.BadRequestNoContent). If you want to surface the validation details (or use a different status), install a schema-error transform middleware via HttpApiMiddleware.layerSchemaErrorTransform:

class ValidationError extends Schema.TaggedError<ValidationError>()(
	'ValidationError',
	{ message: Schema.String, kind: Schema.String }
) {}

class SchemaErrorHandler extends HttpApiMiddleware.Service<SchemaErrorHandler>()(
	'api/SchemaErrorHandler',
	{
		error: ValidationError.pipe(HttpApiSchema.status('UnprocessableEntity'))
	}
) {}

const SchemaErrorHandlerLive = HttpApiMiddleware.layerSchemaErrorTransform(
	SchemaErrorHandler,
	(schemaError, { endpoint }) =>
		Effect.fail(
			new ValidationError({
				kind: schemaError.kind,
				message: `Invalid ${schemaError.kind} for ${endpoint.name}: ${String(schemaError.cause)}`
			})
		)
);

// Attach to an endpoint, group, or the entire API
const Api = HttpApi.make('api')
	.add(/* ... */)
	.middleware(SchemaErrorHandler);

const Live = HttpApiBuilder.layer(Api).pipe(
	Layer.provide(GroupHandlers),
	Layer.provide(SchemaErrorHandlerLive)
);

You can detect this error type explicitly with HttpApiError.HttpApiSchemaError.is(value) and wrap a Schema.SchemaError-failing effect with HttpApiError.HttpApiSchemaError.wrap(kind, effect). SchemaError is no longer a standalone root module; use Schema.SchemaError and Schema.isSchemaError.

Security and Middleware

Security Schemes

HttpApiSecurity.http({ scheme: 'Digest' }); // Authorization: Digest ...
HttpApiSecurity.bearer; // predefined HTTP Bearer auth
HttpApiSecurity.basic; // HTTP Basic auth
HttpApiSecurity.apiKey({
	in: 'header', // "header" | "query" | "cookie"  (default: "header")
	key: 'x-api-key'
});

HttpApiSecurity.bearer is the predefined HTTP Bearer scheme; use HttpApiSecurity.http({ scheme }) for custom Authorization: <scheme> ... schemes such as Digest. Middleware should validate the expected Authorization scheme/prefix itself when it matters: HttpApiBuilder.securityDecode currently slices by scheme length, and security schemes declare credential shape rather than authenticating.

You can attach metadata to a security scheme:

HttpApiSecurity.bearer.pipe(
	HttpApiSecurity.annotate(OpenApi.Description, 'Project-scoped token'),
	HttpApiSecurity.annotate(OpenApi.Format, 'JWT') // becomes bearerFormat in spec
);

const digestAuth = HttpApiSecurity.http({ scheme: 'Digest' }).pipe(
	HttpApiSecurity.annotate(OpenApi.Description, 'Digest token'),
	HttpApiSecurity.annotate(OpenApi.Format, 'DigestToken')
);

Defining Middleware (Service)

class CurrentUser extends Context.Service<CurrentUser, User>()('CurrentUser') {}

class Unauthorized extends Schema.TaggedError<Unauthorized>()(
	'Unauthorized',
	{ message: Schema.String },
	{ httpApiStatus: 401 }
) {}

class Authorization extends HttpApiMiddleware.Service<
	Authorization,
	{
		// Services this middleware injects into the rest of the stack
		provides: CurrentUser;
		// Services this middleware itself depends on
		requires: never;
		// Optional: typed errors the *client* implementation may produce
		clientError: never;
	}
>()('Authorization', {
	// Force clients to provide a matching client middleware (see below)
	requiredForClient: true,
	// Security schemes — keys here become the keys of the security handler record
	security: {
		bearer: HttpApiSecurity.bearer
	},
	// Errors this middleware may raise — single schema or array of schemas
	error: Unauthorized
}) {}

HttpApiMiddleware.Service<Self, Config>() returns a class. The optional second argument controls type-level facets:

Class options (second positional arg):

Implementing Server-Side Security Middleware

Implement the middleware as a Layer. For each entry in security: { ... }, return a handler (httpEffect, options) => Effect<HttpServerResponse, ...> that decodes the credential and provides the resulting service.

const AuthorizationLayer = Layer.effect(
	Authorization,
	Effect.gen(function* () {
		yield* Effect.logInfo('Starting Authorization middleware');

		return Authorization.of({
			bearer: Effect.fn(function* (httpEffect, options) {
				// options.credential — the decoded credential (Redacted for bearer/apiKey, Credentials for basic)
				// options.endpoint  — the endpoint being invoked
				// options.group     — the group being invoked
				const token = Redacted.value(options.credential);
				if (token !== 'valid-token') {
					return yield* new Unauthorized({
						message: 'Invalid token'
					});
				}
				return yield* Effect.provideService(
					httpEffect,
					CurrentUser,
					new User({
						id: UserId.make(1),
						name: 'Dev User',
						email: 'dev@acme.com'
					})
				);
			})
		});
	})
);

When the middleware declares multiple security entries, the framework tries each in order; the first one whose handler succeeds wins.

For one-line handlers, Layer.succeed is convenient:

const AuthLive = Layer.succeed(Authorization)({
	bearer: (effect, opts) =>
		Effect.provideService(effect, CurrentUser, new User(/* ... */))
});

Plain (Non-Security) Middleware

When the middleware has no security, the layer's value is a single function:

class Logger extends HttpApiMiddleware.Service<Logger>()('Http/Logger', {
	error: Schema.String.pipe(
		HttpApiSchema.status('MethodNotAllowed'),
		HttpApiSchema.asText()
	)
}) {}

const LoggerLive = Layer.effect(
	Logger,
	Effect.gen(function* () {
		yield* Effect.logInfo('creating Logger middleware');
		return (httpEffect, { endpoint, group }) =>
			Effect.gen(function* () {
				const request = yield* HttpServerRequest.HttpServerRequest;
				yield* Effect.logInfo(
					`Request: ${request.method} ${request.url} → ${group.identifier}.${endpoint.name}`
				);
				return yield* httpEffect;
			});
	})
);

Schema-Error Transform Middleware

See the "Schema Validation Errors" section above. HttpApiMiddleware.layerSchemaErrorTransform is the canonical primitive for replacing the default empty-400 with a typed validation error.

Applying Middleware

// To a single endpoint
HttpApiEndpoint.get('me', '/me', { success: User }).middleware(Authorization);

// To an entire group (only endpoints already added)
HttpApiGroup.make('users').add(/* ... */).middleware(Authorization);

// To the entire API (only groups already added)
HttpApi.make('api').add(/* ... */).middleware(Authorization);

Middleware Ordering (LIFO)

Multiple middlewares chained on the same endpoint run in last-in, first-out order. Given .middleware(M1).middleware(M2), the runtime order is:

M2-before → M1-before → handler → M1-after → M2-after

The same applies to client-side middleware. Be deliberate about the order if any middleware reads or mutates request/response state from another.

Cookie-Based Security and securitySetCookie

const sessionCookie = HttpApiSecurity.apiKey({ in: 'cookie', key: 'session' });

class Auth extends HttpApiMiddleware.Service<Auth, { provides: CurrentUser }>()(
	'Auth',
	{
		error: Schema.String.annotate({ httpApiStatus: 401 }),
		security: { session: sessionCookie }
	}
) {}

// Setting a security cookie in a login handler:
handlers.handle('login', () =>
	HttpApiBuilder.securitySetCookie(
		sessionCookie,
		Redacted.make('secret-session-id')
	)
);
// Defaults: HttpOnly + Secure. Override via the third options argument.

For testing or custom decoding outside HttpApi, HttpApiBuilder.securityDecode(security) returns Effect<credential, never, HttpServerRequest | ParsedSearchParams>.

Reading Cookies Directly (No Validation, No OpenAPI)

handlers.handle('me', (ctx) => {
	const lang = ctx.request.cookies['lang'] ?? 'en';
	return Effect.succeed(`Language: ${lang}`);
});

These cookies don't appear in the OpenAPI spec and aren't validated. For typed/spec-visible cookies, use a HttpApiSecurity.apiKey({ in: "cookie", ... }) middleware.

Clients

HttpApiClient.make — Service-Based Client

const program = Effect.gen(function* () {
	const client = yield* HttpApiClient.make(Api, {
		baseUrl: 'http://localhost:3000'
	});

	// Methods are grouped: client.GroupName.endpointName(...)
	const users = yield* client.users.list();
	const user = yield* client.users.getById({ params: { id: 1 } });

	// Top-level groups: client.endpointName(...)
	yield* client.health();
});

program.pipe(Effect.provide(FetchHttpClient.layer), Effect.runFork);

make reads HttpClient.HttpClient from context. Provide a platform layer such as FetchHttpClient.layer, BunHttpClient.layer, Node's NodeHttpClient.{layerFetch, layerUndici, layerNodeHttp}, or Browser's BrowserHttpClient.{layerFetch, layerXMLHttpRequest}.

make accepts a transformClient option to wrap the underlying HttpClient (e.g., to set a base URL, attach default headers, enable retries). It also accepts transformResponse and baseUrl.

HttpApiClient.makeWith — Bring Your Own HttpClient

const httpClient = (yield* HttpClient.HttpClient).pipe(
	HttpClient.tapRequest(/* tracing, logging, ... */)
);
const client = yield* HttpApiClient.makeWith(Api, {
	httpClient,
	baseUrl: 'http://localhost:3000'
});

HttpApiClient.group and HttpApiClient.endpoint — Narrow Clients

// One group's endpoints, flat (no `client.users.` prefix):
const usersClient = yield* HttpApiClient.group(Api, {
	group: 'users',
	httpClient: yield* HttpClient.HttpClient
});
yield* usersClient.list();

// A single endpoint as a callable function:
const getUser = yield* HttpApiClient.endpoint(Api, {
	group: 'users',
	endpoint: 'getById',
	httpClient: yield* HttpClient.HttpClient
});
yield* getUser({ params: { id: 1 } });

Wrapping the Client in a Service (Recommended Pattern)

class ApiClient extends Context.Service<
	ApiClient,
	HttpApiClient.ForApi<typeof Api>
>()('app/ApiClient') {
	static readonly layer = Layer.effect(
		ApiClient,
		HttpApiClient.make(Api, {
			transformClient: (client) =>
				client.pipe(
					HttpClient.mapRequest(
						flow(
							HttpClientRequest.prependUrl(
								'http://localhost:3000'
							)
						)
					),
					HttpClient.retryTransient({
						schedule: Schedule.exponential(Duration.millis(100)),
						times: 3
					})
				)
		})
	).pipe(
		Layer.provide(AuthorizationClient), // required client middleware (see below)
		Layer.provide(FetchHttpClient.layer)
	);
}

Response Modes

Each generated client method accepts an optional responseMode:

const client = yield* HttpApiClient.make(Api, { baseUrl });

// Default: just the decoded value
const user = yield* client.users.getById({ params: { id: 1 } });

// Decoded value + raw response (e.g., to inspect headers)
const [user2, response] = yield* client.users.getById({
	params: { id: 1 },
	responseMode: 'decoded-and-response'
});

// Raw response only — no decoding, no typed endpoint errors
const raw = yield* client.users.getById({
	params: { id: 1 },
	responseMode: 'response-only'
});

The old withResponse: true option was renamed to responseMode: "decoded-and-response". Update any pre-rename code accordingly.

Client Middleware

When a server-side HttpApiMiddleware is declared requiredForClient: true, the type system forces every client constructor (make, makeWith, group, endpoint) to be provided with a matching client implementation. Build it with HttpApiMiddleware.layerClient:

const AuthorizationClient = HttpApiMiddleware.layerClient(
	Authorization,
	Effect.fn(function* ({ next, request, endpoint, group }) {
		// next   — pass the request down the chain (and receive the response)
		// request — the outgoing HttpClientRequest
		// endpoint, group — useful for adding instrumentation tagged by endpoint
		return yield* next(HttpClientRequest.bearerToken(request, 'my-token'));
	})
);

// Optional middlewares (no `requiredForClient: true`) can also be wired this way,
// but skipping them simply means the chain skips that layer.

The layerClient second argument can also be an Effect returning the middleware function, for cases where the middleware needs services (e.g., a token from Config):

const AuthorizationClient = HttpApiMiddleware.layerClient(
	Authorization,
	Effect.gen(function* () {
		const token = yield* Config.redacted('API_TOKEN');
		return ({ next, request }) =>
			next(
				HttpClientRequest.bearerToken(request, Redacted.value(token))
			);
	})
);

If a client middleware is declared with a clientError type, that error becomes part of the generated method's error channel.

Client middleware ordering follows the same LIFO rule as server middleware.

Client URL Builder

HttpApiClient.urlBuilder(api, options?) is a synchronous utility that builds typed URLs from your API definition. Methods mirror the client shape, but inputs are encoded via the endpoint's params/query schemas — so the input types are the decoded domain types, not the raw strings.

const Api = HttpApi.make('Api').add(
	HttpApiGroup.make('users').add(
		HttpApiEndpoint.get('getUser', '/users/:id', {
			params: { id: Schema.Finite }, // domain type: number
			query: { page: Schema.Finite } // domain type: number
		})
	)
);

const buildUrl = HttpApiClient.urlBuilder(Api, {
	baseUrl: 'https://api.example.com'
});

buildUrl.users.getUser({ params: { id:

…(truncated)