Changelog

All notable changes to the k0rdent API documentation will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Pre-Release - 2026-02-22

Changed - API Spec MVP Alignment

Revised k0rdent-api.json to reflect MVP scope based on stakeholder review.

Authentication

Added GET /v1/regions/global/auth/sessions — list active sessions for the authenticated user
Added POST /v1/regions/global/auth/sessions — create a browser session (password login with optional MFA)
Added DELETE /v1/regions/global/auth/sessions — end the current session (logout)
Added Session schema to components/schemas with fields: id, userId, ipAddress, userAgent, lastActiveAt, expiresAt, createdAt
Added sessions tag to the Authentication tag group in x-tagGroups

Organization Invitations

createOrganizationInvitation request body: replaced single role string with roles array; added groups array for assigning group membership at invite time; added optional message string for a custom invite email message
Invitation response schema: renamed name → displayName for consistency with all other resource schemas; replaced role string with roles array; added groups array

Roles

Removed POST /v1/regions/global/iam/roles (role creation) — roles are predefined for MVP
Removed PATCH /v1/regions/global/iam/roles/{id} (role update) — roles are predefined for MVP
Removed DELETE /v1/regions/global/iam/roles/{id} (role deletion) — roles are predefined for MVP
GET /v1/regions/global/iam/roles and GET /v1/regions/global/iam/roles/{id} are retained as read-only
Role schema: updated id field to enumerate the four predefined system roles: owner, admin, member, viewer; updated description, example, and selfLink example accordingly
Updated all role name examples throughout the spec to use owner, admin, member, viewer

Scope Levels

Removed folder from all scope enums — API keys, service accounts, and token minting now support only organization and project scope levels
Updated all related field descriptions to remove references to the folder scope level

List Endpoints

All 20 list endpoints now support both cursor-based and offset-based pagination
Added shared component parameters: PageToken (cursor string), PageSize (integer, 1–500, default 50), Offset (integer, default 0)
Added nextPageToken (string) and total (integer) to all list response schemas
pageToken and offset are mutually exclusive — use one per request
Updated info.description to document the dual pagination model

Networks

Updated listNetworks description to note that an optional filter query parameter is under consideration, pending a team decision

Pre-Release - 2026-02-22

Changed - Docs Pipeline Bug Fixes

Build script improvements to fix MDX compilation errors and broken navigation links.

MDX JSX Brace Escaping (`scripts/generate-docs.mts`)

OpenAPI descriptions often contain path parameter references like /groups/{id}/members. When copied verbatim into MDX body text by fumadocs-openapi, bare {identifier} expressions are interpreted as JSX expressions, causing ReferenceError at build time when no matching variable exists.

Added escapeMdxBracesInText() post-processing step that rewrites {id} → \{id\} in plain-text lines of generated MDX files
Escaping is scoped to plain text only — JSX tags, JSX expression blocks ({/* ... */}), and code fences are left untouched
Applied to all tag subdirectory MDX files after doc generation

Endpoint Index Fixes

URL base computation: Endpoint links in index tables now correctly compute their URL path using computeUrlBase(baseDir) rather than splitting on the raw directory string, fixing broken links when directory structure changed
Summary escaping: MDX table cells now escape {, }, and | in endpoint summary text (previously only applied to path strings)
Frontmatter description: Multi-line info.description values from OpenAPI specs are now truncated to a single line before being written to YAML frontmatter, preventing YAML parse errors at build time

Pre-Release - 2026-02-21

Changed - API Spec Consolidation & Build Infrastructure

Merged all 11 individual API specs into a single unified k0rdent-api.json spec and restructured the build pipeline directory layout.

Unified API Spec

All previously separate API specs (arc, atlas, auth, audit, billing, notifications, observability, organizations, regions, webhooks, workflows) have been merged and are now served as a single consolidated OpenAPI document.

New spec location: content/docs/api-docs/generate/k0rdent-api.json
Git-tracked copies: docs/api-docs/k0rdent-api.json and docs/api-docs/k0rdent-api.yaml
Scalar registry: Published as @k0rdent/apis/k0rdent-api@0.2.0-draft

Directory Structure Restructure

Before	After	Purpose
`content/docs/api-docs/src/*.source.json`	`content/docs/api-docs/base/*.base.json`	Source specs (edit these)
`content/docs/api-docs/*.json`	`content/docs/api-docs/bundled/*.json`	Per-spec bundled output
`content/docs/api-docs/*.json`	`content/docs/api-docs/generate/k0rdent-api.json`	Unified spec for doc generation

Updated build pipeline:

`src/lib/openapi.ts` Simplified

Removed dynamic multi-spec filesystem discovery (discoverOpenAPIs(), getOpenAPI(), openapis map)
Now exports a single openapi instance pointing to the unified k0rdent-api.json
Named backward-compatible exports (openapiAtlas, openapiArc, openapiAuth, openapiNotifications) now all alias the unified instance

`scripts/bundle-openapi.mjs` Updated

Source directory changed from ./content/docs/api-docs/src to ./content/docs/api-docs/base
Output directory changed from ./content/docs/api-docs to ./content/docs/api-docs/bundled
Now matches source files by /\.(base\.json|base\.ya?ml)$/ pattern (supports both JSON and YAML sources)

`scripts/generate-docs.mts` and `scripts/regenerate-indexes.mts` Updated

Input directory changed from ./content/docs/api-docs to ./content/docs/api-docs/generate
Both scripts now read only the unified spec rather than scanning all bundled files

API Version Label

Added "version": "0.2.0-draft" to both /api (Scalar hosted) and /local (local file) routes in scalar.config.json

Scalar Config Improvements

Header links (k0rdent AI, k0rdent AI Registry) now open in a new tab ("newTab": true)
Registry link updated to point to the versioned spec: @k0rdent/apis/k0rdent-api@0.2.0-draft
Documentation structure updated to reflect new docs/ asset directory layout

Pre-Release - 2026-02-13 (post-changelog)

Follow-up fixes to the docs build pipeline after the Feb 13 API spec restructure.

Flattened OpenAPI docs: Removed groupBy: tag from doc generation — endpoints are now listed directly under their API spec section without an extra grouping level (fix(scripts): remove groupBy tag and flatten navigation structure)
Spec titles as headers: API section headers now use the spec's info.title (e.g. "Auth & IAM API") rather than the filename (fix(scripts): flatten OpenAPI docs and use spec titles)

Build Order

Fixed pnpm build script to run generate-docs before regenerate-indexes — previously the index regeneration could run against stale generated MDX files (fix(build): generate docs before regenerating indexes)

Script Refactoring

Streamlined endpoint aggregation logic in scripts/generate-docs.mts — consolidated duplicate loops, simplified the per-spec endpoint collection pass (refactor(scripts): streamline endpoint aggregation)

Icons & Labels

Removed " API" suffix from API section titles in sidebar navigation (e.g. "Auth & IAM API" → "Auth & IAM") (fix(scripts): remove API suffix from titles and fix bell icon)
Fixed Notifications API icon: changed bell → Bell (PascalCase required to match Lucide icon exports used by other APIs) (fix(notifications): use PascalCase Bell icon to match other APIs)

Path prefix: All paths migrated from singular /v1/region/ to plural /v1/regions/
Arc API → Compute API: Restructured with focus on clusters, VMs, and SDN (14 endpoint groups)
Atlas API → Infrastructure API: Restructured for bare-metal server lifecycle and inventory (8 endpoint groups)
Auth API → Auth + IAM API: Consolidated authentication and identity/access management (10 endpoint groups)
Organizations extracted: Org/project management moved from individual specs to dedicated organizations spec

API Domain Changes

Compute API (formerly Arc)

14 endpoint groups: clusters, VMs, networks, subnets, addresses, load balancers, peering, interconnects, firewalls
All paths: /v1/regions/{region}/compute/*
Removed: Organization/project paths (moved to organizations spec), storage endpoints, nested network sub-paths
New endpoints:
- /v1/regions/{region}/compute/vms - Virtual machine lifecycle
- /v1/regions/{region}/compute/subnets - Network IP mapping
- /v1/regions/{region}/compute/addresses - IPAM: IP address allocations
- /v1/regions/{region}/compute/loadbalancers - Network load balancing
- /v1/regions/{region}/compute/peering - Within-region routing
- /v1/regions/{region}/compute/interconnects - Region-to-region routing
- /v1/regions/{region}/compute/firewalls - Network policy
- /v1/regions/{region}/compute/clusters/{clusterId}/kubeconfigs - Kubeconfig issuance
- /v1/regions/{region}/compute/clusters/{clusterId}/nodes/{nodeId}/ssh - Node SSH access

Infrastructure API (formerly Atlas)

8 endpoint groups: servers CRUD, batch enrollment, batch/single actions, logs, profiles, switches
All paths: /v1/regions/{region}/infrastructure/*
Removed: Organization/project/quota paths, compute paths, storage paths
New endpoints:
- /v1/regions/{region}/infrastructure/servers/batch - Bulk server enrollment (POST with array)
- /v1/regions/{region}/infrastructure/servers/actions - Batch actions on multiple servers (POST with {action, ids})
- /v1/regions/{region}/infrastructure/servers/{id}/actions - Single server actions (provision, validate, state transitions)
- /v1/regions/{region}/infrastructure/servers/{id}/logs - Host provisioning & status logs
- /v1/regions/{region}/infrastructure/profiles - Profiles/Persona CRUD
- /v1/regions/{region}/infrastructure/switches - Network management

Auth + IAM API (formerly Auth)

10 endpoint groups: tokens, sessions, users, user profiles, roles, groups, policies, service accounts, API keys, identity providers
All paths: /v1/regions/global/auth/* and /v1/regions/global/iam/*
Removed: Old auth paths (me, signup, invitations, organizations, members)
New endpoints:
- /v1/regions/global/auth/tokens - OAuth2/OIDC token acquire/refresh/revoke
- /v1/regions/global/auth/sessions - Session login/logout, list active sessions, MFA
- /v1/regions/global/iam/users - Tenant user lifecycle
- /v1/regions/global/iam/users/profile - Self-service profile
- /v1/regions/global/iam/roles - Authorization/RBAC role definitions
- /v1/regions/global/iam/groups - Group management (SSO-driven, IAM policy bindings)
- /v1/regions/global/iam/policies - Role bindings at org/project/resource level
- /v1/regions/global/iam/service-accounts - Machine identity for automation
- /v1/regions/global/iam/apikeys - API key lifecycle management
- /v1/regions/global/iam/providers - Identity provider configuration (SSO)

Organizations API (new)

6 endpoint groups: organizations CRUD, org invitations, org quotas, folders (stub), projects, project quotas
All paths: /v1/regions/global/organizations/* and /v1/regions/global/projects/*
New spec consolidating org/project management previously scattered across arc, atlas, auth
Key decision: Projects are top-level at /v1/regions/global/projects (org context from auth token, not URL nesting)
Endpoints:
- /v1/regions/global/organizations - Organization CRUD
- /v1/regions/global/organizations/{orgId}/invitations - Organization invitations
- /v1/regions/global/organizations/quotas - Customer org quota management
- /v1/regions/global/organizations/folders - Folder management (stub — hierarchy TBD)
- /v1/regions/global/projects - Top-level project management
- /v1/regions/global/projects/quotas - Project quota management

Webhooks API (new)

3 endpoint groups: webhooks, subscriptions, delivery history
All paths: /v1/regions/global/webhooks/*
Endpoints:
- /v1/regions/global/webhooks - Webhook management
- /v1/regions/global/webhooks/subscriptions - Webhook subscriptions
- /v1/regions/global/webhooks/subscriptions/{id}/deliveries - Delivery history

Workflows API (new, internal-only)

4 endpoint groups: workflow definitions, workflow runs, run logs, metrics
All paths: /v1/regions/global/workflows/*
Marked as internal-only — for platform orchestration, not public API
Endpoints:
- /v1/regions/global/workflows - Workflow definitions/orchestration
- /v1/regions/global/workflows/{id}/runs - Workflow execution instances
- /v1/regions/global/workflows/{id}/runs/{runId}/logs - Workflow run logs
- /v1/regions/global/workflows/metrics - Aggregate performance stats

Observability API (new, stub)

1 endpoint: stub for future analytics & observability
Path: /v1/regions/global/observability

Audit API (simplified)

Path changed from /v1/region/{region}/audit/events to /v1/regions/global/audit
Single collection endpoint per spreadsheet spec

Billing API (simplified)

Path changed from /v1/region/global/billing/accounts/... to /v1/regions/global/projects/billing
Single endpoint per spreadsheet spec

Regions API (renamed)

Path changed from /v1/region/global/regions to /v1/regions/global/locations

Notifications API (prefix update)

Prefix updated from /v1/region/global/ to /v1/regions/global/
Existing endpoint structure preserved

Schema Changes

Common Schemas (added)

Quota - Resource quota configuration with enforcement policies (hard/soft)
Folder - Project organization hierarchy (stub — full design TBD)

Compute Schemas (new)

VM - Virtual machine definition
Subnet - Network subnet configuration
Address - IPAM IP address allocation
LoadBalancer - Load balancer configuration
PeeringConnection - Within-region network routing
Interconnect - Region-to-region network routing
Firewall - Network policy rules

Infrastructure Schemas (new)

Profile - Server profile/persona definition
Switch - Network switch management
ServerAction - Action enum: provision, validate, start, stop, restart, decommission

Auth + IAM Schemas (new)

Token - OAuth2/OIDC token
Session - User session
User - Tenant user
Role - RBAC role definition
Group - User group
Policy - IAM policy (role bindings)
ServiceAccount - Machine identity
ApiKey - API key credential
IdentityProvider - SSO provider configuration

Organizations Schemas

Organization, Project, Member, Invitation - Moved to organizations spec (previously scattered)
Folder - Stub for project hierarchy
Quota - Resource quota (shared schema)

Key Design Decisions

Path naming: Plural /v1/regions/ per Google Sheet (singular was incorrect)
Project URLs: Flat top-level /v1/regions/global/projects (org context from auth token, not URL nesting) — cleaner, less cluttered
IAM consolidation: IAM endpoints folded into auth spec (single identity domain)
Workflows visibility: Internal-only (still documented for platform developers)
Instance types: Dropped for MVP (not in spreadsheet)
Infrastructure actions: Both single (/servers/{id}/actions) and batch (/servers/actions) endpoints for flexibility
Batch enrollment: Dedicated /servers/batch endpoint (POST array of servers)
Folders: Stub only (GCP-style hierarchy design TBD)
VMs vs Instances: Use /compute/vms terminology (not /compute/instances)

Files Changed

Source specs edited (7):

content/docs/api-docs/src/arc.base.json - Rewritten as Compute API
content/docs/api-docs/src/atlas.base.json - Rewritten as Infrastructure API
content/docs/api-docs/src/auth.base.json - Rewritten as Auth + IAM API
content/docs/api-docs/src/audit.base.json - Simplified to single endpoint
content/docs/api-docs/src/billing.base.json - Simplified to single endpoint
content/docs/api-docs/src/regions.base.json - Path renamed to /locations
content/docs/api-docs/src/notifications.base.json - Prefix updated

Source specs created (4):

content/docs/api-docs/src/organizations.base.json - New Organizations API
content/docs/api-docs/src/webhooks.base.json - New Webhooks API
content/docs/api-docs/src/workflows.base.json - New Workflows API (internal)
content/docs/api-docs/src/observability.base.json - New Observability stub

Common files updated (1):

content/docs/api-docs/common/schemas.json - Added Quota and Folder schemas

Generated/bundled files (22):

All corresponding *.json files in content/docs/api-docs/ and docs/api-docs/
Auto-generated MDX documentation in content/docs/(generated)/

Statistics

38 files changed: +16,571 insertions, -77,336 deletions (net -60,765 lines)
11 API specs: arc, atlas, auth, audit, billing, notifications, observability, organizations, regions, webhooks, workflows
48 unique endpoints from Google Sheet MVP requirements
100+ MDX pages generated via fumadocs-openapi

✅ pnpm bundle-openapi - 11 specs bundled successfully
✅ pnpm generate-docs - 100+ MDX pages generated
✅ pnpm build - Site builds successfully (209+ pages)
✅ Path prefix verification - Zero singular /v1/region/ paths remain
✅ Spreadsheet coverage - All 48 MVP endpoints mapped

References

Source of Truth: k0rdent API Spec Google Sheet
Implementation Plan: .claude/plans/velvety-doodling-willow.md

Prior to 2026-02-13

No structured changelog maintained before this date. See git history for previous changes.

On this page