Serve Multiple API Versions from a Single Laravel App

Many applications need to expose more than one API surface at the same time — a legacy v1 for existing clients, a v2 for new integrations, and perhaps a private internal API for admin tooling. Geni handles this with native multi-document support: define named versions in config/geni.php and Geni registers dedicated routes, JSON spec endpoints, and MCP discovery endpoints for every version, plus a version-switcher dropdown in the docs portal sidebar.

Configuration

Define each version under the apis key in config/geni.php. Each entry accepts a title, version, description, and the api_path prefix Geni should scan. You can also supply a custom routes callback to narrow exactly which routes belong to a version.

config/geni.php

'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 a dedicated set of 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`

Each version’s JSON spec is generated independently from source — no shared state, no cross-version leakage.

Interactive Version Switcher

When you define more than one API, an interactive dropdown appears in the documentation portal sidebar. Selecting a different version switches the displayed specification in place without a full page reload and updates the browser URL via history.pushState(), so users can bookmark or share a direct link to any version.

Visiting the root /docs/api URL automatically redirects to the first configured API version in the apis array, so your existing links never break when you add a new version.

CLI Support

Every Geni CLI command accepts an --api flag to target a specific named version. Use this in CI scripts, pre-commit hooks, or deployment pipelines to scope an operation to exactly one spec.

# Export the v2 specification to a file
php artisan geni:export --api=v2 --path=v2.json

# Check the v1 specification for drift against a committed file
php artisan geni:check --api=v1 --path=v1.json

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

Getting Started

Core Concepts

Integrations

Annotations

Guides

Reference

Serve Multiple API Versions from a Single Laravel App

Configuration

Generated Endpoints

Interactive Version Switcher

CLI Support

​Configuration

​Generated Endpoints

​Interactive Version Switcher

​CLI Support

Configuration

Generated Endpoints

Interactive Version Switcher

CLI Support