# Effect HTTP API

> Build typed HTTP APIs with Effect's HttpApi — endpoints with schemas, handlers, security middleware, OpenAPI docs, derived clients, and handler unit tests. Use when building HTTP servers, REST APIs, or typed HTTP clients with Effect v4.

- Skill: `mpsuesser/effect-http-api` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mpsuesser/effect-http-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mpsuesser/effect-http-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: mpsuesser (https://skillmd.com/u/mpsuesser)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mpsuesser/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

```ts
// 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

```ts
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

```ts
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:

```ts
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`.

```ts
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:

```ts
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

```ts
// 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.

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

### Prefixing

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

Group- and API-level prefixing are described below.

## Schema Annotations

### Status Codes

```ts
// 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:

```ts
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.

```ts
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

```ts
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

```ts
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

```ts
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.

```ts
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

```ts
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

```ts
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

```ts
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

```ts
// 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

```ts
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

```ts
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).

```ts
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:

```ts
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.

```ts
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.

```ts
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:

```ts
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`:

```ts
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.

```ts
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

```ts
// 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:

```ts
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.

| Class                 | Status | NoContent variant              |
| --------------------- | ------ | ------------------------------ |
| `BadRequest`          | 400    | `BadRequestNoContent`          |
| `Unauthorized`        | 401    | `UnauthorizedNoContent`        |
| `Forbidden`           | 403    | `ForbiddenNoContent`           |
| `NotFound`            | 404    | `NotFoundNoContent`            |
| `MethodNotAllowed`    | 405    | `MethodNotAllowedNoContent`    |
| `NotAcceptable`       | 406    | `NotAcceptableNoContent`       |
| `RequestTimeout`      | 408    | `RequestTimeoutNoContent`      |
| `Conflict`            | 409    | `ConflictNoContent`            |
| `Gone`                | 410    | `GoneNoContent`                |
| `InternalServerError` | 500    | `InternalServerErrorNoContent` |
| `NotImplemented`      | 501    | `NotImplementedNoContent`      |
| `ServiceUnavailable`  | 503    | `ServiceUnavailableNoContent`  |

Usage:

```ts
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`:

```ts
{
  _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`:

```ts
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

```ts
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:

```ts
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)

```ts
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:

| Field               | Meaning                                                                              |
| ------------------- | ------------------------------------------------------------------------------------ |
| `provides`          | Services that the middleware adds to the handler context                             |
| `requires`          | Services that the middleware depends on                                              |
| `clientError`       | Typed error that the *client-side* counterpart may fail with (when `requiredForClient: true`) |

Class options (second positional arg):

| Field                | Meaning                                                                       |
| -------------------- | ----------------------------------------------------------------------------- |
| `error`              | One schema or an array of schemas the middleware may produce as failures      |
| `security`           | A record of named `HttpApiSecurity` schemes (defines security middleware)     |
| `requiredForClient`  | If `true`, generated clients require a matching `layerClient` to be provided  |

### 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.

```ts
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:

```ts
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:

```ts
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

```ts
// 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`

```ts
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)

```ts
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

```ts
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`

```ts
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

```ts
// 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)

```ts
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`:

| Mode                       | Return type                                  | Errors include `Schema.SchemaError` + endpoint errors? |
| -------------------------- | -------------------------------------------- | ------------------------------------------------ |
| `"decoded-only"` (default) | `Success`                                    | yes                                              |
| `"decoded-and-response"`   | `[Success, HttpClientResponse]` tuple        | yes                                              |
| `"response-only"`          | `HttpClientResponse` (no decoding performed) | no — only `HttpClientError` and middleware errors |

```ts
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`:

```ts
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`):

```ts
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.

```ts
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)