.. include:: /Includes.rst.txt

.. _configuration-provider:

===============
Provider fields
===============

Providers represent API connections with credentials.

.. figure:: /Images/backend-providers.png
   :alt: LLM providers list with connection status
   :class: with-border with-shadow
   :zoom: lightbox

   Provider list showing adapter type, endpoint,
   API key status, and action buttons.

.. _configuration-provider-required:

Required
========

.. confval:: identifier
   :name: confval-provider-identifier
   :type: string
   :required: true

   Unique slug for programmatic access
   (e.g., ``openai-prod``, ``ollama-local``).

.. confval:: name
   :name: confval-provider-name
   :type: string
   :required: true

   Display name shown in the backend.

.. confval:: adapter_type
   :name: confval-provider-adapter-type
   :type: string
   :required: true

   The protocol to use:

   - ``openai`` — OpenAI API
   - ``anthropic`` — Anthropic Claude API
   - ``gemini`` — Google Gemini API
   - ``ollama`` — Local Ollama instance
   - ``openrouter`` — OpenRouter multi-model API
   - ``mistral`` — Mistral AI API
   - ``groq`` — Groq inference API
   - ``azure_openai`` — Azure OpenAI Service
   - ``custom`` — OpenAI-compatible endpoint

.. confval:: api_key
   :name: confval-provider-api-key
   :type: string

   API key for authentication. Stored as a
   `nr-vault <https://github.com/netresearch/t3x-nr-vault>`__
   UUID identifier (envelope encryption).
   nr-llm never stores raw API keys in the
   database. Required for cloud providers
   (OpenAI, Claude, Gemini, etc.); not required
   for local providers like Ollama.

.. _configuration-provider-optional:

Optional
========

.. confval:: endpoint_url
   :name: confval-provider-endpoint-url
   :type: string
   :Default: (adapter default)

   Custom API endpoint URL.

.. confval:: organization_id
   :name: confval-provider-organization-id
   :type: string
   :Default: (empty)

   Organization ID (OpenAI, Azure). Sent as the `OpenAI-Organization`
   request header by the OpenAI-compatible adapters (`openai`,
   `azure_openai`, `together`, `fireworks`, `perplexity`, `custom`).

.. confval:: timeout
   :name: confval-provider-timeout
   :type: integer
   :Default: 120

   Maximum time in seconds to wait for the complete API response. A
   configuration- or model-level timeout overrides this value per request.

.. confval:: max_retries
   :name: confval-provider-max-retries
   :type: integer
   :Default: 3

   Number of retries after the first failed request (0 = try once, no
   retries). Timed-out requests are not retried.

.. confval:: options
   :name: confval-provider-options
   :type: JSON
   :Default: {}

   Additional adapter-specific options. Supported key:

   `customHeaders`
      Object mapping header names to values, sent on every API request
      (including streaming), for example:

      .. code-block:: json

         {"customHeaders": {"X-Custom-Header": "value"}}

      Custom headers are applied after the adapter's own headers, so a
      colliding name overrides the adapter value — a mistyped
      `Content-Type` breaks that provider's calls.

   .. note::

      A per-provider `proxy` is not supported; TYPO3's global HTTP proxy
      configuration (`$GLOBALS['TYPO3_CONF_VARS']['HTTP']['proxy']`)
      applies to all outgoing provider requests.