# Docs


- **Getting started**
- [What is Kizuna.js?](/docs): A spec-driven framework for building fully typed REST APIs in TypeScript, where your route declarations produce the validation, the documentation, the clients, and the AI tools.
- [Quickstart](/docs/quickstart): Declare your routes, serve them on your framework, and call them from a typed client in 8 minutes.
- [Config](/docs/config): Assemble your API in kizuna.config.ts, mount it, and say where its generated clients go.
- [Project Structure](/docs/project-structure): Where your declarations, your config, and your clients live.

- **Writing routes**
- [Routes](/docs/routes): Declare a route, the schemas it takes and answers with, and the handler that serves it.
- [Streaming](/docs/streaming): Declare a route that answers with a stream of typed events, write the handler as an async generator, and read it back with for await in the fetch client.
- [Caching](/docs/caching): Declare on a response how it may be cached, and have Kizuna send the Cache-Control and Vary headers and document them in OpenAPI.
- [Deprecations](/docs/deprecations): Declare deprecations and sunset dates on a route and have them reach your editor, OpenAPI, Swift, Kotlin, and the Deprecation and Sunset response headers.
- [Tools](/docs/tools): Publish a route as a tool a model can call, and read each call typed in your client.

- **Security**
- [Authentication](/docs/authentication): Say who can call your API. An identity is a credential you accept, a guard turns it into the caller, and the handler receives them typed.
- [Access Control](/docs/access-control): Declare the roles callers hold and say who may call each route. Kizuna checks the caller's role before the handler runs.
- [OAuth](/docs/oauth): Verify tokens from an authorization server. Declare the identity, secure the routes, verify in the guard, and serve the discovery document.

- **Running your API**
- Adapters
  - [Express](/docs/adapters/express): Mount a Kizuna API on an Express 5 application.
  - [Fastify](/docs/adapters/fastify): Mount a Kizuna API on a Fastify application.
  - [Hono](/docs/adapters/hono): Mount a Kizuna API on a Hono application.
  - [Next.js](/docs/adapters/next): Mount a Kizuna API on a Next.js App Router catch-all route.
- [Request Context](/docs/request-context): Declare request-scoped values every handler receives, typed, resolved once per request.
- [Jobs](/docs/jobs): Declare background and scheduled jobs next to their handlers, run them or queue them from your own code, and connect any queue you already run.

- **Clients**
- Clients
  - [Fetch](/docs/clients/fetch): A fully typed HTTP client for consuming Kizuna routes in the browser, on the server, or in React Native.
  - [TanStack Query](/docs/clients/tanstack-query): Build TanStack Query options from your routes, with query keys derived from your routes.
  - [Swift](/docs/clients/swift): Generate a native Swift client from your routes, using URLSession and Codable.
  - [Kotlin](/docs/clients/kotlin): Generate a native Kotlin client from your routes, using OkHttp and kotlinx.serialization.

- **Plugins**
- [OpenAPI](/docs/openapi): Generate an OpenAPI 3.1.0 document from your routes, and serve it with a reference UI.
- [MCP](/docs/mcp): Install the MCP plugin so AI assistants can call your API as tools, on any adapter.

- **Tooling**
- [CLI](/docs/cli): Write your types and clients, print the routes your config serves, and compare an API against a git ref.
- [ESLint](/docs/eslint): Catch Kizuna mistakes in your editor with the official ESLint plugin.
- [Breaking Changes](/docs/breaking-changes): Catch a change that breaks callers before it ships.

- **Build your own**
- Extend
  - [Create a Plugin](/docs/extend/create-plugin): Write a plugin once and it runs on every adapter, because it never touches your framework.
  - [Create an Adapter](/docs/extend/create-adapter): Build and ship your own Kizuna adapter for any HTTP runtime using createAdapter from kizunajs/adapter.
  - [Create a Generator](/docs/extend/create-generator): Build and ship your own code generator or client from a Kizuna API using createGenerator.
  - [Create a Job Transport](/docs/extend/create-job-transport): Connect any queue or scheduler to your Kizuna jobs by implementing one function.
  - [Create a TypeScript Client Wrapper](/docs/extend/create-ts-client): Build and ship your own TypeScript client wrapper using the types and the route metadata @kizunajs/fetch carries.

- **Reference**
- [Standards](/docs/standards): The specifications Kizuna follows, what each one covers, and what it deliberately leaves out.
- [Zod](/docs/zod): Routes are written in Zod, and the schema carries more than validation.
- API Reference
  - [API Reference](/docs/reference): Every function, schema and plugin kizuna exports, with its options and types.
  - [new Kizuna()](/docs/reference/kizuna): The authoring surface for one API, typed by the Config that kizuna generate writes.
  - [k.tags](/docs/reference/k-tags): Declare the set of tags used to group routes across nested route trees and the OpenAPI spec.
  - [k.identity](/docs/reference/k-identity): Declare who can call your API, the context a passing guard provides, the roles its callers hold, and the guard that authenticates them.
  - [Kizuna.roles](/docs/reference/kizuna-roles): Declare the roles callers hold, as names or built from a permission catalog.
  - [Kizuna.permissions](/docs/reference/kizuna-permissions): Declare every permission an API has, for roles to hold and routes to require.
  - [k.requestContext](/docs/reference/k-request-context): Provide request-scoped values to every handler, typed, such as analytics ids, loggers, and the caller's locale.
  - [Kizuna.model](/docs/reference/kizuna-model): Give a Zod schema a name so the OpenAPI document and every generated client produce named types instead of inline definitions.
  - [k.route](/docs/reference/k-route): Define one route and the handler that answers it, with inputs, auth and the return all typed from the route.
  - [k.routes](/docs/reference/k-routes): Define a group of routes under one tag, with full path-param and response checking.
  - [k.jobs](/docs/reference/k-jobs): Declare your API's scheduled jobs, with their schedules, inputs, and results.
  - [k.issue](/docs/reference/k-issue): Emit a validation issue with a machine-readable code, checked against the codes your config declares.
  - [defineConfig](/docs/reference/define-config): Assemble everything one API is made of, and get back the api you mount.
  - [createClient()](/docs/reference/create-client): Create a fully typed HTTP client from the file kizuna generate writes, using the native fetch API.
  - [new KizunaTanstackQuery()](/docs/reference/kizuna-tanstack-query): Build TanStack Query options from a Kizuna fetch client.
  - [ProblemDetailsSchema](/docs/reference/problem-details-schema): RFC 9457 Problem Details error response schema (ProblemDetailsSchema) used across kizuna.
  - [BinarySchema & FileSchema](/docs/reference/binary-and-file-schemas): Helper schemas for binary response bodies (BinarySchema) and multipart upload fields (FileSchema).
  - [ProtectedResourceMetadataSchema](/docs/reference/protected-resource-metadata-schema): RFC 9728 Protected Resource Metadata schema, builder, and challenge formatting.
  - [isValidationError](/docs/reference/is-validation-error): Type guard to distinguish Kizuna validation errors from custom 400 responses on the client.
  - [isUndeclaredResponseError](/docs/reference/is-undeclared-response-error): Narrow a TanStack Query error to a response whose status the route does not declare.
  - [generateOpenApi](/docs/reference/generate-openapi): Generate an OpenAPI 3.1.0 document from a Kizuna api.
  - [openApiPlugin](/docs/reference/openapi-plugin): Serve your OpenAPI document and an API reference UI for it, on any adapter.
  - [generateSwiftClient](/docs/reference/generate-swift-client): Generate a native Swift client from a Kizuna API with URLSession and Codable.
  - [generateKotlinClient](/docs/reference/generate-kotlin-client): Generate a native Kotlin client from a Kizuna API with OkHttp, kotlinx.serialization, and coroutines.
  - [mcpPlugin](/docs/reference/mcp-plugin): Install an MCP (Model Context Protocol) endpoint so AI assistants can call your API as tools.
  - [createMcpServer](/docs/reference/create-mcp-server): Create a raw MCP server from a Kizuna API for use with any transport (stdio, SSE, etc.).
- Migration
  - [Migrating an existing API](/docs/migration/existing-api): Move an existing API onto Kizuna without breaking deployed clients, using the additive pattern and the escape hatch for the rest.
  - [Migrating from ts-rest](/docs/migration/from-ts-rest): Side-by-side comparison of ts-rest and Kizuna, for anyone weighing a ts-rest alternative, with notes on deliberate differences.