> ## Documentation Index
> Fetch the complete documentation index at: https://team.k0labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Complete OpenAPI documentation for k0rdent Atlas, Arc, and shared services APIs

## Overview

<Error>
  **Draft:** This documentation is currently a work in progress and subject to change.
</Error>

This document provides an overview of the k0rdent API shape, covering Atlas (Provider Console), Arc (Customer AI Console), and shared services like Auth.

<Note>
  **Core Concept:** Atlas maps, Arc deploys, k0rdent executes.
</Note>

{/* - Platform APIs handle CAPI, Kubernetes, KubeVirt, OpenStack, networking, storage, GPU, and other infrastructure technologies */}

***

## 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.

<Columns cols={2}>
  <Card title="Arc API" href="/arc" icon="plane-departure">
    Self-service portal for AI/ML workload deployment and cluster management
  </Card>

  <Card title="Atlas API" href="/atlas" icon="globe">
    Internal infrastructure management for bare metal, k0rdent clusters, and VMs
  </Card>
</Columns>

<Columns cols={2}>
  <Card title="Auth API" href="/auth" icon="key">
    Centralized authentication with OAuth, session management, and multi-tenant support
  </Card>

  <Card title="Notifications API" href="/notifications" icon="bell">
    In-app/email/slack notification management
  </Card>
</Columns>

***

## Early Draft Endpoints

These endpoints are still in their earlier days

<Columns cols={2}>
  <Card title="Audit API" href="/audit" icon="search">
    Self-service portal for AI/ML workload deployment and cluster management
  </Card>

  <Card title="Billing API" href="/billing" icon="money-bill">
    Internal infrastructure management for bare metal, k0rdent clusters, and VMs
  </Card>
</Columns>

<Columns cols={2}>
  <Card title="Regions API" href="/regions" icon="globe">
    Centralized authentication with OAuth, session management, and multi-tenant support
  </Card>

  <Card title="Better Auth API" href="/better-auth" icon="lock">
    Better authentication with OAuth, session management, and multi-tenant support
  </Card>
</Columns>

***

## 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`](/atlas/addresses)    | IP address allocations                 |
| [`/v1/region/global/compute/clusters`](/atlas/clusters)      | Kubernetes cluster deployments         |
| [`/v1/region/global/compute/networks`](/atlas/networks)      | Network configuration and topology     |
| [`/v1/region/global/infrastructure/servers`](/atlas/servers) | Bare metal server lifecycle management |
| [`/v1/region/global/infrastructure/storage`](/atlas/storage) | Storage resource management            |
| [`/v1/region/global/organizations`](/atlas/organizations)    | Customer organization management       |
| [`/v1/region/global/projects`](/atlas/projects)              | Customer project management            |
| [`/v1/region/global/invitations`](/atlas/invitations)        | Organization/Project invite management |

### Arc API (api.example.com)

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

### Shared Services (Both Domains)

#### Auth API

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

#### Notifications API

| Endpoint                                                              | Purpose                                |
| --------------------------------------------------------------------- | -------------------------------------- |
| [`/v1/region/global/notifications`](/notifications)                   | Create In-app/email/slack notification |
| [`/v1/region/global/notifications/inbox`](/notifications/inbox)       | In-app/email/slack notifications       |
| [`/v1/region/global/notifications/settings`](/notifications/settings) | Notification settings                  |

## Future Planned

| Endpoint                                    | Purpose               |
| ------------------------------------------- | --------------------- |
| [`/v1/region/global/audit`](/audit)         | Audit logs            |
| [`/v1/region/global/billing`](/billing)     | Billing               |
| [`/v1/region/global/analytics`](/analytics) | Analytics             |
| [`/v1/region/global/webhooks`](/webhooks)   | Webhook subscriptions |

## TBD/WIP

<Warning>
  To be discussed and engineered on what and where these endpoints will be.
</Warning>

| 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.

<Warning>
  **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.
</Warning>

<Note>
  **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.
</Note>

***

## 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