# Apache Maka API Documentation: Complete Guide to Public Interfaces and Runtime Usage

> Explore the Apache Maka API documentation for public interfaces and runtime usage. Master session management with SessionManager and orchestrate turns efficiently.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: api-reference
- Published: 2026-09-11

---

**Yes, Apache Maka exposes a stable public API through the `@maka/runtime` package, with `SessionManager` serving as the main façade for session management and turn orchestration, while internal implementations remain free to evolve behind the public seam.**

Apache Maka organizes its TypeScript codebase around a **stable public seam** that protects consumers from internal refactoring. The official **Apache Maka API documentation** is distributed across architecture guides, package READMEs, and source code barrels that explicitly define supported entry points. All public interfaces are re-exported through root index files, allowing developers to interact with the system without knowledge of internal file layouts.

## Public API Entry Points

The `@maka/runtime` package serves as the primary interface for Apache Maka consumers. According to the source code, the package explicitly declares its public API through barrel exports in [`packages/runtime/src/index.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/index.ts), while keeping implementation details in sub-directories.

### SessionManager Facade

The **`SessionManager`** class in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) acts as the central façade for all runtime interactions. This class provides external APIs for creating sessions, sending messages, and managing turn orchestration. Consumers instantiate this class directly to control the conversation lifecycle.

### BackendRegistry and AgentBackend

The **`BackendRegistry`** (located in [`packages/runtime/src/backend-registry.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/backend-registry.ts)) implements a registry pattern for plugging in model backends. Developers can register custom implementations of the **`AgentBackend`** interface to support different AI providers or testing mocks. The default production implementation, **`AiSdkBackend`**, resides in [`packages/runtime/src/ai-sdk-backend.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/ai-sdk-backend.ts) and handles communication with external model providers.

### RuntimeKernel and Built-in Tools

The **`RuntimeKernel`** in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) manages the core orchestration layer that runs individual turns and coordinates events. For tool access, the **`buildBuiltinTools()`** factory function in [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) creates the standard tool suite including web-search and file-access capabilities. The **`WorkspaceExecutor`** in [`packages/runtime/src/workspace-executor.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/workspace-executor.ts) abstracts filesystem and shell side-effects for these tools.

### UI Components via @maka/ui

The **`@maka/ui`** package exports a stable component library through its barrel at [`packages/ui/src/index.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/index.ts). Only components explicitly included in this index file are part of the public API, ensuring backward compatibility for UI integrations.

## Where to Find Official Documentation

Apache Maka distributes its API documentation across several markdown files in the repository rather than a single hosted site.

### Architecture Overview

The **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** file at the repository root provides a high-level component diagram showing how `SessionManager` functions as the public entry point. This document defines the conceptual boundaries between public APIs and internal implementation details.

### Package READMEs

The **[`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md)** explicitly states which exports constitute the supported public API and which sub-paths are considered internal. This file serves as the contract for semantic versioning guarantees.

### Technical Walkthroughs

The **[`docs/archive/maka-core-tech-walkthrough.md`](https://github.com/apache/maka/blob/main/docs/archive/maka-core-tech-walkthrough.md)** contains a detailed walkthrough of the public API surface, explaining the relationship between `SessionManager` and the internal kernel. This document demonstrates how the public façade delegates to `RuntimeKernel` for turn execution.

## Practical Usage Examples

The following examples demonstrate how to interact with the Apache Maka API using the public exports from `@maka/runtime` and `@maka/ui`.

### Creating Sessions and Sending Messages

To begin using the runtime, import `SessionManager` and `BackendRegistry` from the package barrel:

```typescript
import { SessionManager, BackendRegistry, AiSdkBackend } from '@maka/runtime';

// Register the default AI SDK backend (e.g., OpenAI)
BackendRegistry.register('openai', new AiSdkBackend({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY!,
}));

// Instantiate the public façade
const manager = new SessionManager({});

// Create a new session
const sessionId = await manager.createSession({ name: 'demo-session' });

// Send a user message; turn orchestration runs inside the runtime kernel
const response = await manager.sendMessage(sessionId, {
  role: 'user',
  content: 'What is the capital of France?'
});

console.log('Assistant reply:', response.content);

```

*Key files referenced*: `SessionManager` ([`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)), `BackendRegistry` ([`packages/runtime/src/backend-registry.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/backend-registry.ts)), `AiSdkBackend` ([`packages/runtime/src/ai-sdk-backend.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/ai-sdk-backend.ts)).

### Registering Custom Backends

You can extend the system with custom backends by implementing the `AgentBackend` interface:

```typescript
import { BackendRegistry, AgentBackend, SessionManager } from '@maka/runtime';

class MockBackend implements AgentBackend {
  async streamChat(_messages: unknown[]) {
    return { content: 'Mock answer', done: true };
  }
}

// Register under a custom name
BackendRegistry.register('mock', new MockBackend());

// Use the mock backend for a new session
const manager = new SessionManager();
await manager.setBackend('mock');
const sid = await manager.createSession();
const reply = await manager.sendMessage(sid, { role: 'user', content: 'Hello' });
console.log(reply.content); // → "Mock answer"

```

*Key file*: `AgentBackend` interface is defined in [`packages/runtime/src/types.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/types.ts) and re-exported by the barrel.

### Integrating UI Components

Import components from the `@maka/ui` barrel for use in React applications:

```tsx
import { Button } from '@maka/ui';

export function MyApp() {
  return (
    <Button onClick={() => alert('Clicked!')}>
      Click me
    </Button>
  );
}

```

Only components exported through [`packages/ui/src/index.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/index.ts) are part of the stable public API.

## Summary

- **Apache Maka** exposes a stable public API through the `@maka/runtime` and `@maka/ui` packages, with all entry points re-exported through root barrel files.
- **`SessionManager`** in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) serves as the primary façade for session CRUD operations and message handling.
- **`BackendRegistry`** and the **`AgentBackend`** interface enable pluggable model backends, with `AiSdkBackend` provided as the default production implementation.
- Official documentation resides in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), [`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md), and [`docs/archive/maka-core-tech-walkthrough.md`](https://github.com/apache/maka/blob/main/docs/archive/maka-core-tech-walkthrough.md), which collectively define the public seam and usage patterns.
- The **`buildBuiltinTools()`** factory and **`WorkspaceExecutor`** provide standardized tool capabilities with abstracted side-effect management.

## Frequently Asked Questions

### Where is the Apache Maka API documentation hosted?

Apache Maka does not currently maintain a separate hosted documentation site. Instead, the official **Apache Maka API documentation** lives directly in the repository at [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), [`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md), and the `docs/` directory. These markdown files define the public API contract and provide architectural context.

### What is the main entry point for the Apache Maka runtime API?

The **`SessionManager`** class exported from `@maka/runtime` serves as the main entry point. According to the source code in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), this class provides the public façade for creating sessions, sending messages, and managing turn orchestration, while delegating execution to the internal `RuntimeKernel`.

### How do I create a custom backend for Apache Maka?

Implement the **`AgentBackend`** interface from `@maka/runtime`, then register your implementation using **`BackendRegistry.register()`**. As implemented in [`packages/runtime/src/backend-registry.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/backend-registry.ts), this registry pattern allows you to plug in alternative model providers or testing mocks without modifying the core runtime code.

### Are the UI components in `@maka/ui` part of the stable API?

Yes, but only components explicitly exported from [`packages/ui/src/index.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/index.ts) are considered part of the stable public API. The package employs a barrel export pattern to ensure that internal component refactoring does not break consumer imports, making the index file the authoritative source for supported UI components.