Mark this endpoint as requiring authorization.
Overloads:
authorize(principalSchema, ...roles) — typed principal, optional role requirementsauthorize(...roles) — untyped principal (unknown), optional role requirementsIf no roles are specified, any authenticated user is allowed.
Mark this endpoint as requiring authorization.
Overloads:
authorize(principalSchema, ...roles) — typed principal, optional role requirementsauthorize(...roles) — untyped principal (unknown), optional role requirementsIf no roles are specified, any authenticated user is allowed.
Define the request body schema. Validation failures return 422 Problem Details.
Declare a cache group for this endpoint.
Use on GET / query endpoints to group responses into a named cache. The client-side {@code cacheTags} middleware caches responses keyed by this tag and flushes matching entries when a mutation calls clearsCacheTag.
Simple tag (no properties — single cache entry). Tag with property descriptors for fine-grained keys.
Declare a cache group for this endpoint.
Use on GET / query endpoints to group responses into a named cache. The client-side {@code cacheTags} middleware caches responses keyed by this tag and flushes matching entries when a mutation calls clearsCacheTag.
Simple tag (no properties — single cache entry). Tag with property descriptors for fine-grained keys.
Declare callbacks for OpenAPI spec generation.
Callbacks describe async out-of-band requests that may be sent to a URL
provided in the request body, emitted as the callbacks field on the
OpenAPI Operation Object.
Record mapping callback names to CallbackDefinition objects.
Declare which cache groups are cleared when this mutation succeeds.
Use on POST / PUT / PATCH / DELETE endpoints. When the mutation completes, the {@code cacheTags} client middleware invalidates all cache entries matching the declared tag names (prefix match).
Simple tag (clears all entries prefixed with the name). Tag with property descriptors for targeted invalidation.
Declare which cache groups are cleared when this mutation succeeds.
Use on POST / PUT / PATCH / DELETE endpoints. When the mutation completes, the {@code cacheTags} client middleware invalidates all cache entries matching the declared tag names (prefix match).
Simple tag (clears all entries prefixed with the name). Tag with property descriptors for targeted invalidation.
Mark this endpoint as deprecated in OpenAPI spec output.
Longer description for OpenAPI operation objects. Supports Markdown.
Provide a single example value for the request body.
Emitted as the example field on the OpenAPI Media Type Object
(application/json). Pre-fills the "Try it out" panel in Swagger UI.
An example request body value.
Provide named examples for the request body.
Each entry is emitted under the examples map of the OpenAPI Media Type
Object following the Example Object shape ({ summary?, description?, value }).
A record of named examples.
Link external documentation to this operation.
Emitted as the externalDocs field on the OpenAPI Operation Object.
The URL to the external documentation.
Optionaldescription: stringOptional short description of the external docs.
Define an expected request headers schema (must be an object schema).
Declare DI services to be resolved per-request and passed as the second handler argument.
Return an immutable snapshot of this builder's configuration as EndpointMetadata.
Declare response links for OpenAPI spec generation.
Links describe follow-up actions that can be taken based on the response,
emitted under the primary 2xx response's links map.
Record mapping link names to LinkDefinition objects.
A unique, stable identifier for this operation in OpenAPI spec.
Declare that this endpoint can produce responses in multiple content types.
Each key is a MIME type. Provide an optional schema to override the
default response schema for that type; otherwise the schema from
.returns() / .responses() is reused for every declared content type.
When used alongside .producesFile(), the binary response takes precedence.
Map of MIME type → optional schema override.
Declare that this endpoint produces a binary file response.
When set, the OpenAPI spec emits a binary content type instead of a JSON
schema for the success response. Takes precedence over .returns().
OptionalcontentType: stringMIME type (default: 'application/octet-stream').
Optionaldescription: stringOptional response description for the spec.
Mark this endpoint as public — no authentication required.
Calling .public() sets authRoles to null, overriding any
previously set authorization requirements (from .authorize() or
an inherited scoped factory).
Define the query string schema (must be an object schema). Validation failures return 422.
Declare response headers emitted by this endpoint.
The object schema's properties become header names in the OpenAPI spec;
each property's sub-schema and description are emitted in the headers
map on every response code.
Object schema whose properties describe the response headers.
Declare per-status-code response schemas for OpenAPI generation and handler return-type enforcement.
Pass null as the schema for body-less codes (e.g. 204).
const ep = endpoint
.get('/api/todos/:id')
.responses({
200: object({ id: number(), title: string() }),
404: object({ message: string() }),
});
const handler: Handler<typeof ep> = ({ params }) => {
const todo = todos.get(params.id);
if (!todo) return ActionResult.notFound({ message: 'Not found' });
return todo; // plain object → 200
};
Declare the response type for OpenAPI spec generation.
Overloads:
returns<T>() — generic type only, no runtime schemareturns(schema) — provides a schema for spec generation and type inferenceDeclare the response type for OpenAPI spec generation.
Overloads:
returns<T>() — generic type only, no runtime schemareturns(schema) — provides a schema for spec generation and type inferenceShort, human-readable summary for OpenAPI operation objects.
OpenAPI tags grouping this operation in generated documentation.
Mark this endpoint as accepting multipart/form-data file uploads.
When set, the server parses the request body with a streaming multipart
parser instead of the default JSON deserializer. File fields are made
available to the handler via arg.files (a Record<string, FilePart>),
while non-file form fields are validated against the body schema and
available via arg.body.
Optionaloptions: UploadOptionsUpload configuration (max file size, allowed MIME types, etc.).
const UploadAvatar = endpoint
.post('/api/avatar')
.upload({ maxFileSize: 2 * 1024 * 1024, allowedMimeTypes: ['image/*'] })
.authorize(PrincipalSchema)
.responses({ 200: AvatarSchema });
const handler: Handler<typeof UploadAvatar> = async ({ files }) => {
const avatar = files['avatar'];
// avatar: { filename, mimeType, buffer, size }
};
The full path for this endpoint, combining
basePathandpathTemplate.For static routes this is the exact URL path (e.g.
"/todos"). For dynamic routes the template placeholders are included (e.g."/todos/:id").