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