Overview This document provides an overview of the k0rdent API shape, covering Atlas (Provider Console), Arc (Customer AI Console), and shared services like Auth.
Core Concept: Atlas maps, Arc deploys, k0rdent executes.
RFC Endpoints Request for Comments (RFC) endpoints are endpoints that are being proposed for discussion and feedback. They are not fully implemented yet, but are subject to change.
Arc API Self-service portal for AI/ML workload deployment and cluster management
Atlas API Internal infrastructure management for bare metal, k0rdent clusters, and VMs
Auth API Centralized authentication with OAuth, session management, and multi-tenant support
Notifications API In-app/email/slack notification management
Early Draft Endpoints These endpoints are still in their earlier days
Audit API Self-service portal for AI/ML workload deployment and cluster management
Billing API Internal infrastructure management for bare metal, k0rdent clusters, and VMs
Regions API Centralized authentication with OAuth, session management, and multi-tenant support
Better Auth API Better authentication with OAuth, session management, and multi-tenant support
API Domain Architecture k0rdent uses domain-based API routing to separate Atlas (internal provider operations) from Arc (customer-facing operations):
Previously Domain Purpose /api/v1/atlasapi.internal.example.comAtlas API /api/v1/arcapi.example.comArc API auth / notifications / etcBoth domains Shared services
API Endpoint Reference Atlas API (api.internal.example.com) Arc API (api.example.com) Shared Services (Both Domains) Auth API Notifications API Future Planned TBD/WIP To be discussed and engineered on what and where these endpoints will be.
Endpoint Purpose /v1/region/edge/auth/verifyEdge runtime auth verify
Atlas API (api.internal.example.com): Endpoint Purpose /v1/region/global/poolsDynamic inventory resource filters /v1/region/global/stacksInfrastructure templates /v1/region/global/vmsVirtual machine lifecycle
Arc API (api.example.com): Endpoint Purpose /v1/region/{region}/stacksRead-only infrastructure template stacks /v1/region/{region}/inferenceInference endpoint lifecycle /v1/region/{region}/trainingTraining job lifecycle /v1/region/{region}/vmsVirtual machine lifecycle /v1/region/{region}/deploysRequest infrastructure /v1/region/{region}/infrastructureCapacity queries across resource types
TBD - Direct API Access The following APIs are being evaluated for direct API access. Implementation and availability are to be determined.
Workflows API Workflow orchestration for long-running operations. Built on Trigger.dev.
Note: Direct API access to Workflows is under evaluation. The current implementation uses Trigger.dev for workflow orchestration. Whether to expose direct API endpoints for workflow management is being determined based on use cases and security considerations.
Design Principle: All infrastructure mutations flow through workflows.
This provides durable execution, automatic retries, audit trails, and
observability. Workflows double as the event log for the platform.
API Changelog This section tracks API endpoint changes and iterations to help understand the evolution of the k0rdent API specification.
2026-02-04 - Endpoint Restructuring Summary : Reorganized API endpoints under domain-based paths and removed implicit /v1 prefix from all documentation.Removes internal codename arc and atlas from the API endpoint paths Previously Domain Purpose /api/v1/atlasapi.internal.example.comAtlas API /api/v1/arcapi.example.comArc API auth / notifications / etcBoth domains Shared services
Old Path New Path /api/v1/servers/v1/region/global/infrastructure/servers/api/v1/networks/v1/region/global/compute/networks/api/v1/addresses/v1/region/global/compute/addresses/api/v1/pools/v1/region/global/pools (unchanged, just remove prefix)/api/v1/stacks/v1/region/global/stacks (unchanged, just remove prefix)/api/v1/clusters/v1/region/global/compute/clusters/api/v1/organizations/v1/region/global/organizations/api/v1/storage/v1/region/global/infrastructure/storage
Old Path New Path /api/v1/projects/v1/region/{region}/projects/api/v1/stacks/v1/region/{region}/stacks (unchanged, just remove prefix)/api/v1/clusters/v1/region/{region}/compute/clusters/api/v1/secrets (Phase2+)/v1/region/{region}/compute/clusters/:clusterId/kubeconfigs
Auth API (Both Domains) Old Path New Path /api/v1/auth/me/v1/region/global/auth/me/api/v1/auth/session/v1/region/global/auth/session/api/v1/auth/organizations/v1/region/global/auth/organizations/api/v1/auth/invitations/v1/region/global/auth/invitations
Future Old Path New Path /api/v1/audit/v1/region/global/audit/api/v1/billing/v1/region/global/billing/api/v1/analytics/v1/region/global/analytics/api/v1/webhooks/*/v1/region/global/webhooks/* (moved to Future)/api/v1/inventory/v1/region/global/infrastructure
Moved to TBD Section
Workflows API - move to new section, TBD if we expose direct API access to workflows
