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

# Upgrading to 3.0

> Step-by-step guide for upgrading Geni from 2.x to 3.0.

## Overview

Geni 3.0 documents responses exactly as Laravel sends them, fixes the security issues found in a review of 2.0.1, and is tested on Laravel 10, 11, 12 and 13.

Update the package:

```bash theme={null}
composer require masitings/geni-api:^3.0
```

Then go through the steps below. Most applications only need steps 1 and 2.

<Steps>
  <Step title="Opt in to MCP tools/call over HTTP (if you use it)">
    `tools/call` on `POST /docs/api/mcp` is now disabled by default. To keep it, enable it explicitly:

    ```env .env theme={null}
    GENI_MCP_HTTP_EXECUTION=true
    ```

    If you published `config/geni.php`, add the key to the `mcp` block:

    ```php config/geni.php theme={null}
    'mcp' => [
        // ...
        'http_execution' => (bool) env('GENI_MCP_HTTP_EXECUTION', false),
    ],
    ```

    MCP clients must now send `Content-Type: application/json` (other requests get `415`). The stdio server `php artisan geni:mcp:serve` is unaffected. See [MCP](/guides/mcp#enabling-http-execution) for the security implications.
  </Step>

  <Step title="Regenerate committed specs">
    Generated documents changed shape:

    * Resource responses are wrapped in `data` (or the resource's `$wrap` key).
    * Paginated collections use `{data, links, meta}`.
    * Create endpoints are documented as `201`.
    * Every operation has an `operationId`.

    Regenerate every spec checked by `geni:check`:

    ```bash theme={null}
    php artisan geni:export --path=openapi.json

    # once per named API
    php artisan geni:export --api=v1 --path=openapi-v1.json
    php artisan geni:export --api=v2 --path=openapi-v2.json
    ```

    If `geni.cache.enabled` is on, run `php artisan geni:clear` (with the same `--api`) first, because `geni:export` serves a cached document when one exists.
  </Step>

  <Step title="Define a viewApiDocs gate for non-local access (optional)">
    Outside `local`, docs still return 404 unless you define a `viewApiDocs` gate. When the gate passes, the docs are served; when it denies, the response is `403`:

    ```php app/Providers/AppServiceProvider.php theme={null}
    Gate::define('viewApiDocs', fn (?User $user) => $user?->isAdmin());
    ```

    User-based gates need a session: add `'web'` to `geni.middleware`. Without a gate nothing changes. See [Documentation Authentication](/guides/authentication#the-viewapidocs-gate).
  </Step>

  <Step title="Check your docs credentials">
    Blank `GENI_DOCS_USERNAME` / `GENI_DOCS_PASSWORD` now mean "no credentials gate". Setting only one of them locks the docs. If you rely on the credentials gate, make sure **both** values are set.
  </Step>

  <Step title="Use only configured API names">
    `?api=` values and `--api` options must be `default` or a key of `geni.apis`. Unknown names now return `404` (HTTP) or fail (Artisan) instead of silently using the default document. Check CI scripts that pass `--api`.
  </Step>

  <Step title="Update custom code that reads the document">
    * Operation extensions are now top-level keys (`x-unauthenticated`, `x-api`, `x-geni-unresolved`) instead of being nested under `x-geni-unresolved`.
    * Resource schemas list `required` keys and may use `anyOf` / `const`.
  </Step>
</Steps>

## What Else Is New

* [Eloquent resource inference](/integrations/eloquent-resources) that follows Laravel's own serialization, including conditional keys, nested resources and status codes.
* [Customization API](/guides/customization): `Geni::configure()`, transformers, `geni.extensions`, `geni.servers` and automatic operation IDs.
* [Scalar and Stoplight Elements renderers](/guides/renderers) and Markdown descriptions in the built-in portal.
* Operation titles and descriptions read from [PHPDoc](/annotations/phpdoc#summary-and-description).
* `geni:cache`, `geni:check`, `geni:export` and `geni:analyze` now honor `--api`. See the [CLI reference](/reference/cli).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.