CLI
Every centrakit CLI command and global flag, how it signs in and resolves the API base URL, its configuration files and environment variables, and how releases are packaged.
Docs for AI agents
How AI agents and LLM tools read the CentraKit docs through llms.txt, Markdown page URLs, the docs MCP server and Ask AI, and how they act on CentraKit data through the product MCP server.
CLI
Every centrakit CLI command and global flag, how it signs in and resolves the API base URL, its configuration files and environment variables, and how releases are packaged.
Docs for AI agents
How AI agents and LLM tools read the CentraKit docs through llms.txt, Markdown page URLs, the docs MCP server and Ask AI, and how they act on CentraKit data through the product MCP server.
Where the CentraKit OpenAPI 3.2 specification lives, how it is generated from route JSDoc and Zod schemas, and how the TypeScript client, reference pages and drift check are built from it.
The CentraKit REST API is described by one OpenAPI 3.2 document. It is generated from the route handlers in apps/api, committed to git, and used to build the TypeScript client, the MCP tool catalog, the CLI api command and the API reference pages in these docs.
| Format | Location |
|---|---|
| Raw spec | https://api.centrakit.com/openapi.json, committed as apps/api/public/openapi.json |
| Interactive reference | https://api.centrakit.com/api-docs, a Scalar reference. The API root redirects there. |
| Docs reference pages | The OpenAPI section of these docs, one page per operation. |
The spec currently has 175 paths and 259 operations in 36 tags. Paths start with /v1, and the servers are https://api.centrakit.com/api and https://api.localhost/api, so full URLs look like https://api.centrakit.com/api/v1/health.
The Scalar reference prefills your bearer token when you are signed in on the same domain, so you can try requests from the page. It shows operation IDs, which are the names used by the TypeScript client, the CLI and the MCP tools.
| Scheme | Meaning |
|---|---|
SessionCookie | The Supabase session cookie set by the SaaS app or the login route. |
BearerAuth | Authorization: Bearer <access-token>. |
Most operations accept either. See Authentication.
The pipeline has two steps, both run by one command:
pnpm openapi:generatepnpm --filter api openapi:generate runs openapi-gen generate from next-openapi-gen with apps/api/openapi-gen.config.mts. It scans apps/api/app/api and writes apps/api/public/openapi.json.pnpm --filter @workspace/api-client generate runs Hey API (@hey-api/openapi-ts) over that file and writes the client to packages/api-client/src/generated.Only route handlers with an @openapi tag in their JSDoc are included. Request and response shapes come from Zod schemas, which the generator resolves by name from apps/api/app/api and the shared contract packages listed in the config's schemaDir. A typical handler:
/**
* List tags.
* @description Return tags for an organization, optionally filtered by kind.
* @operationId listTags
* @tag Tags
* @auth SessionCookie,bearer
* @pathParams tagsParamsSchema
* @queryParams tagsOpenApiListQuerySchema
* @response 200:tagsListResponseSchema
* @responseDescription Returns paginated tags.
* @responseSet resource
* @openapi
*/
export const GET = withApiRoute(/* ... */);| Tag | Purpose |
|---|---|
@operationId | Stable operation name, used by the client, the CLI and MCP. |
@tag | Group in the reference. Tags are declared in the config. |
@description | Longer operation description. |
@auth | Accepted security schemes. |
@pathParams | Zod schema for path parameters. |
@queryParams | Zod schema for query parameters. |
@body or @requestBody | Zod schema for the request body. @requestBody ... required marks it required. |
@bodyDescription | Request body description. |
@contentType | Non-JSON request content type, such as multipart/form-data uploads. |
@response | Success status and Zod schema, such as 201:organizationTagSchema. |
@responseDescription | Success response description. |
@responseSet | Which shared error responses to add. |
@openapi | Includes the handler in the spec. |
Error responses use problem details, application/problem+json with the problemDetailsSchema component. @responseSet picks the statuses that are added to an operation:
| Set | Statuses |
|---|---|
public | 400, 500. The default. |
auth | 400, 401, 403, 500 |
organizations | 400, 401, 403, 404, 409, 500 |
resource | 400, 401, 403, 404, 409, 500 |
Each shared response includes an example whose type points to a code on Errors. The generator runs with diagnostics set to fail on errors, so a broken schema reference stops generation.
@workspace/api-client is the generated client. Hey API runs with three plugins:
@hey-api/typescript for request and response types;zod for request and response schemas;@hey-api/sdk for one function per operation, returning { data, error } fields and validating requests with the Zod schemas.| Export | Contents |
|---|---|
@workspace/api-client | createApiClient, requestApiOperation, apiSdk, types, Zod schemas and the operation catalog. |
@workspace/api-client/generated/sdk | The generated operation functions. |
@workspace/api-client/generated/zod | The generated Zod schemas. |
@workspace/api-client/operations | getOperationById and getOperationCatalog. |
@workspace/api-client/mcp | The MCP tool definitions and catalog, and executeMcpApiOperation, which the MCP server uses to call operations. |
import { apiSdk, createApiClient } from "@workspace/api-client";
const client = createApiClient({
baseUrl: "https://api.centrakit.com/api",
accessToken,
});
const { data, error } = await apiSdk.listTasks({
client,
path: { organizationId },
query: { limit: 50 },
});requestApiOperation calls an operation by its runtime operation ID. The CLI api command uses it. It is untyped on purpose, because Hey API does not emit an operation ID map that could type a dynamic call.
The client package is internal to the monorepo and is not published to npm. External integrations can generate their own client from openapi.json with any OpenAPI 3.2 generator.
Hey API 0.99 needs the classic TypeScript compiler API, so the generate script loads scripts/register-typescript6.mjs, which redirects typescript imports to the typescript6 package during generation only. The committed output is type-checked by the repository's TypeScript 7 compiler with strict settings, including exactOptionalPropertyTypes.
The generated fetch runtime passes explicit undefined for a few optional fields. scripts/postprocess-generated-runtime.mjs replaces those known assignments in the generated client and core runtime files with conditional properties. The transform is idempotent, has its own tests, and fails generation when the upstream code no longer matches. The SDK functions, types and Zod schemas are not changed.
The docs app reads apps/api/public/openapi.json with fumadocs-openapi and generates one page per operation under the OpenAPI section. Each page also has a Markdown version that contains only that page's operations and the component schemas they reference, which keeps it small enough for AI agents. See Docs for AI agents.
After you change route JSDoc, a route's Zod schema or a shared contract schema:
pnpm openapi:generate.{} in openapi.json. An empty component means the generator could not resolve the schema, usually because its file is outside schemaDir.apps/api/public/openapi.json and packages/api-client/src/generated together with the route change.CI runs an OpenAPI drift check in the verify workflow:
pnpm openapi:generate
git diff --exit-code -- apps/api/public/openapi.json packages/api-client/src/generatedThe check fails when the committed artifacts do not match a fresh generation. Run the same commands locally before you push. See CI and release.
limit and offset as strings instead of integers, so the generated client types them as strings: listTags, listCustomerAssets, listNotifications, listTemplates, the webhook delivery, destination and endpoint lists, the workflow definition and run lists, and the inventory allocation, movement and stock record lists. listOrganizationAuditEvents has the same issue for offset.Last updated on
CLI
Every centrakit CLI command and global flag, how it signs in and resolves the API base URL, its configuration files and environment variables, and how releases are packaged.
Docs for AI agents
How AI agents and LLM tools read the CentraKit docs through llms.txt, Markdown page URLs, the docs MCP server and Ask AI, and how they act on CentraKit data through the product MCP server.