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.
Early Draft Endpoints
These endpoints are still in their earlier days
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/atlas | api.internal.example.com | Atlas API |
/api/v1/arc | api.example.com | Arc API |
auth / notifications / etc | Both 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/verify | Edge runtime auth verify |
| Endpoint | Purpose |
|---|
/v1/region/global/pools | Dynamic inventory resource filters |
/v1/region/global/stacks | Infrastructure templates |
/v1/region/global/vms | Virtual machine lifecycle |
| Endpoint | Purpose |
|---|
/v1/region/{region}/stacks | Read-only infrastructure template stacks |
/v1/region/{region}/inference | Inference endpoint lifecycle |
/v1/region/{region}/training | Training job lifecycle |
/v1/region/{region}/vms | Virtual machine lifecycle |
/v1/region/{region}/deploys | Request infrastructure |
/v1/region/{region}/infrastructure | Capacity 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/atlas | api.internal.example.com | Atlas API |
/api/v1/arc | api.example.com | Arc API |
auth / notifications / etc | Both 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
