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

# Multi-Version API Documentation

> Configure multiple named API specifications with interactive version switching.

## Overview

Many applications maintain multiple API versions simultaneously (e.g. `v1`, `v2`) or separate internal APIs from public APIs.

Geni includes native multi-document support with an interactive version switcher dropdown in the documentation portal sidebar.

## Configuration

Define named versions under the `apis` key in `config/geni.php`:

```php config/geni.php theme={null}
'apis' => [
    'v1' => [
        'title' => 'API v1 (Legacy)',
        'version' => '1.4.0',
        'description' => 'Legacy API specification for mobile clients v1.x.',
        'api_path' => 'api/v1',
    ],
    'v2' => [
        'title' => 'API v2 (Latest)',
        'version' => '2.0.0',
        'description' => 'Current production API specification.',
        'api_path' => 'api/v2',
    ],
    'internal' => [
        'title' => 'Internal Admin API',
        'version' => '1.0.0',
        'api_path' => 'api/internal',
        'routes' => function () {
            return Route::getRoutes()->getByAction('App\Http\Controllers\Admin\*');
        },
    ],
],
```

## Generated Endpoints

When named APIs are configured, Geni automatically registers dedicated routes for each version:

| Version    | Interactive UI       | JSON Specification        | MCP Discovery Endpoint   |
| ---------- | -------------------- | ------------------------- | ------------------------ |
| `v1`       | `/docs/api/v1`       | `/docs/api/v1.json`       | `/docs/api/v1/mcp`       |
| `v2`       | `/docs/api/v2`       | `/docs/api/v2.json`       | `/docs/api/v2/mcp`       |
| `internal` | `/docs/api/internal` | `/docs/api/internal.json` | `/docs/api/internal/mcp` |

Visiting the root `/docs/api` automatically redirects to the first configured API version.

## Interactive Version Switcher

When `> 1` APIs are defined, an interactive dropdown appears in the documentation portal sidebar:

<Frame>
  <div className="p-4 bg-slate-900 rounded-lg text-white font-mono text-sm">
    <div className="flex items-center space-x-2 border border-slate-700 p-2 rounded">
      <span>API v2 (Latest)</span>
      <span className="text-slate-400">▼</span>
    </div>
  </div>
</Frame>

Selecting a different version switches specifications in-place without a full page reload and updates the browser URL via `history.pushState()`.

## CLI Support

All CLI commands accept an `--api` option to target a specific named specification:

```bash theme={null}
# Export v2 specification
php artisan geni:export --api=v2 --path=v2.json

# Check v1 specification for drift
php artisan geni:check --api=v1 --path=v1.json

# Run MCP server scoped to v2
php artisan geni:mcp:serve --api=v2
```