API Overview

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/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)

Endpoint	Purpose
`/v1/region/global/compute/addresses`	IP address allocations
`/v1/region/global/compute/clusters`	Kubernetes cluster deployments
`/v1/region/global/compute/networks`	Network configuration and topology
`/v1/region/global/infrastructure/servers`	Bare metal server lifecycle management
`/v1/region/global/infrastructure/storage`	Storage resource management
`/v1/region/global/organizations`	Customer organization management
`/v1/region/global/projects`	Customer project management
`/v1/region/global/invitations`	Organization/Project invite management

Arc API (api.example.com)

Endpoint	Purpose
`/v1/region/{region}/compute/clusters`	Kubernetes cluster deployments
`/v1/region/{region}/compute/clusters/:clusterId/kubeconfigs`	Cluster kubeconfig access
`/v1/region/{region}/compute/storage`	Storage resource management
`/v1/region/{region}/compute/networks`	Network configuration and topology
`/v1/region/{region}/organizations`	Customer organization management
`/v1/region/{region}/projects`	Resource grouping/membership within organization
`/v1/region/{region}/invitations`	Project invitation management

Shared Services (Both Domains)

Auth API

Endpoint	Purpose
`/v1/region/global/auth/me`	User profile and session
`/v1/region/global/auth/session`	Session management
`/v1/region/global/auth/organizations`	Self-service organization management
`/v1/region/global/auth/invitations`	Organization invitation acceptance
`/v1/region/global/auth/users/signup`	User signup
`/v1/region/global/auth/providers`	Which OAuth providers are enabled

Notifications API

Endpoint	Purpose
`/v1/region/global/notifications`	Create In-app/email/slack notification
`/v1/region/global/notifications/inbox`	In-app/email/slack notifications
`/v1/region/global/notifications/settings`	Notification settings

Future Planned

Endpoint	Purpose
`/v1/region/global/audit`	Audit logs
`/v1/region/global/billing`	Billing
`/v1/region/global/analytics`	Analytics
`/v1/region/global/webhooks`	Webhook subscriptions

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

Atlas API (api.internal.example.com):

Endpoint	Purpose
`/v1/region/global/pools`	Dynamic inventory resource filters
`/v1/region/global/stacks`	Infrastructure templates
`/v1/region/global/vms`	Virtual machine lifecycle

Arc API (api.example.com):

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

Atlas API (api.internal.example.com)

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`

Arc API (api.example.com)

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

Platform APIs

Shared API Spec

Apps Team APIs Dev

Draft APIs

Archived APIs

Overview

RFC Endpoints

Arc API

Atlas API

Auth API

Notifications API

Early Draft Endpoints

Audit API

Billing API

Regions API

Better Auth API

API Domain Architecture

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

TBD - Direct API Access

Workflows API

API Changelog

2026-02-04 - Endpoint Restructuring

Removes internal codename arc and atlas from the API endpoint paths

Atlas API (api.internal.example.com)

Arc API (api.example.com)

Auth API (Both Domains)

Future

Moved to TBD Section

​Overview

​RFC Endpoints

Arc API

Atlas API

Auth API

Notifications API

​Early Draft Endpoints

Audit API

Billing API

Regions API

Better Auth API

​API Domain Architecture

​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

​TBD - Direct API Access

​Workflows API

​API Changelog

​2026-02-04 - Endpoint Restructuring

​Removes internal codename arc and atlas from the API endpoint paths

​Atlas API (api.internal.example.com)

​Arc API (api.example.com)

​Auth API (Both Domains)

​Future

​Moved to TBD Section

Overview

RFC Endpoints

Early Draft Endpoints

API Domain Architecture

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

TBD - Direct API Access

Workflows API

API Changelog

2026-02-04 - Endpoint Restructuring

Removes internal codename arc and atlas from the API endpoint paths

Atlas API (api.internal.example.com)

Arc API (api.example.com)

Auth API (Both Domains)

Future

Moved to TBD Section