# Lemon AI Provider Settings Schema: Platform Configuration Structure Explained

> Explore the Lemon AI provider settings schema. Discover the structured JSON format that defines platform configuration for Search Provider Setting API endpoints. Learn more now.

- Repository: [hexdocom/lemonai](https://github.com/hexdocom/lemonai)
- Tags: api-reference
- Published: 2026-03-03

---

**Lemon AI defines provider settings through a strict JSON schema located at [`public/schemas/provider_setting_result.json`](https://github.com/hexdocom/lemonai/blob/main/public/schemas/provider_setting_result.json) that structures the data returned by the Search Provider Setting API endpoints.**

The platform configuration in Lemon AI separates generic platform metadata from provider-specific search configurations through a dedicated schema structure for provider settings. This schema governs how third-party search credentials, behavior toggles, and display properties are validated, stored, and returned via the `/api/search_provider_setting` REST endpoints.

## Provider Settings Schema Definition

Lemon AI stores each user’s search-provider configuration as a **JSON schema** that describes the exact shape of objects returned by PUT and GET requests to `/api/search_provider_setting`. The schema file [`public/schemas/provider_setting_result.json`](https://github.com/hexdocom/lemonai/blob/main/public/schemas/provider_setting_result.json) serves as the single source of truth for API documentation and validation.

### Core Properties and Data Types

The schema defines thirteen distinct properties that control provider integration and search behavior:

- **`id`** (integer) — Primary key of the setting record in the database.
- **`provider_id`** (integer) — Foreign key referencing the provider definition in [`public/schemas/provider.json`](https://github.com/hexdocom/lemonai/blob/main/public/schemas/provider.json).
- **`provider_name`** (string) — Human-readable display name of the search provider.
- **`base_config`** (object) — Container for provider-specific credentials such as `api_key` and `endpoint` URLs.
- **`logo_url`** (string) — HTTPS URL pointing to the provider’s brand logo asset.
- **`api_key`** (string) — The user’s API credential, mirrored from `base_config` for convenience in responses.
- **`include_date`** (boolean) — Toggle determining whether search results display date metadata.
- **`cover_provider_search`** (boolean) — When `true`, bypasses the platform’s built-in search in favor of the provider’s native search implementation.
- **`enable_enhanced_mode`** (boolean) — Activates additional processing layers such as LLM-enhanced result summarization.
- **`result_count`** (integer) — Pagination control specifying the desired number of results per query.
- **`blacklist`** (string) — Comma-separated list of exclusion terms filtered from search results.
- **`create_at`** (string, date-time) — ISO 8601 timestamp recording when the configuration was first created.
- **`update_at`** (string, date-time) — ISO 8601 timestamp indicating the last modification time.

## API Integration and Schema References

The Search Provider Setting router in [`src/routers/search_provider_setting/setting.js`](https://github.com/hexdocom/lemonai/blob/main/src/routers/search_provider_setting/setting.js) implements the schema through Swagger documentation references. The router handles both retrieval and modification of user-specific provider configurations.

When assembling API responses, the router aggregates data from two separate database models and conforms the output to the [`provider_setting_result.json`](https://github.com/hexdocom/lemonai/blob/main/provider_setting_result.json) structure. The Swagger specification references this schema using:

```javascript
// swagger response schema reference
*               $ref: './schemas/provider_setting_result.json'

```

This ensures that generated API documentation remains synchronized with the actual validation rules enforced by the platform.

## Database Models and Storage Architecture

The schema structure maps to two distinct Sequelize models that separate credential storage from behavioral preferences:

**[`src/models/UserProviderConfig.js`](https://github.com/hexdocom/lemonai/blob/main/src/models/UserProviderConfig.js)** stores the sensitive `base_config` object containing the `api_key` and `endpoint` values. This isolation allows for encrypted storage of credentials separately from user preferences.

**[`src/models/UserSearchSetting.js`](https://github.com/hexdocom/lemonai/blob/main/src/models/UserSearchSetting.js)** manages the boolean toggles and numeric settings including `include_date`, `cover_provider_search`, `enable_enhanced_mode`, `result_count`, and `blacklist`. These fields control the search experience without containing sensitive authentication data.

During a PUT request, the router maps incoming JSON payloads onto these models, then assembles the unified response object that conforms to the [`provider_setting_result.json`](https://github.com/hexdocom/lemonai/blob/main/provider_setting_result.json) schema.

## Implementation Examples

### Updating Provider Settings via API

To create or modify a provider configuration, send a PUT request with the required `provider_id` and configuration options:

```bash
curl -X PUT http://localhost:3000/api/search_provider_setting \
  -H "Content-Type: application/json" \
  -d '{
        "provider_id": 3,
        "api_key": "my-secret-key",
        "endpoint": "https://api.example.com/v1",
        "include_date": true,
        "cover_provider_search": false,
        "enable_enhanced_mode": true,
        "result_count": 10,
        "blacklist": "spam,advertisement"
      }'

```

The platform returns a structured response matching the schema definition:

```json
{
  "code": 200,
  "data": {
    "id": 12,
    "provider_id": 3,
    "provider_name": "Talivy",
    "base_config": {
      "api_key": "my-secret-key",
      "endpoint": "https://api.example.com/v1"
    },
    "logo_url": "https://static.example.com/logo.png",
    "api_key": "my-secret-key",
    "include_date": true,
    "cover_provider_search": false,
    "enable_enhanced_mode": true,
    "result_count": 10,
    "blacklist": "spam,advertisement",
    "create_at": "2024-11-07T14:23:12.000Z",
    "update_at": "2024-11-07T14:23:12.000Z"
  },
  "msg": "Successfully upserted user provider config"
}

```

### Validating Payloads Against the Schema

When implementing client-side or middleware validation in Node.js, you can reference the schema properties directly:

```javascript
const Joi = require('joi');

// Schema validation matching provider_setting_result.json structure
const providerSettingSchema = Joi.object({
  id: Joi.number().integer(),
  provider_id: Joi.number().integer().required(),
  provider_name: Joi.string(),
  base_config: Joi.object({
    api_key: Joi.string().required(),
    endpoint: Joi.string().uri().required()
  }),
  logo_url: Joi.string().uri(),
  api_key: Joi.string().allow(''),
  include_date: Joi.boolean().default(false),
  cover_provider_search: Joi.boolean().default(false),
  enable_enhanced_mode: Joi.boolean().default(false),
  result_count: Joi.number().integer().min(1).max(100),
  blacklist: Joi.string().allow(''),
  create_at: Joi.date().iso(),
  update_at: Joi.date().iso()
});

function validateProviderSetting(payload) {
  const { error, value } = providerSettingSchema.validate(payload);
  if (error) throw new Error(`Invalid provider setting: ${error.message}`);
  return value;
}

```

## Relationship to Platform Configuration

The **platform configuration** schema defined in [`public/schemas/platform.json`](https://github.com/hexdocom/lemonai/blob/main/public/schemas/platform.json) contains generic platform fields such as `id`, `name`, `logo`, and global API credentials. However, the **provider-specific** configuration lives exclusively within the [`provider_setting_result.json`](https://github.com/hexdocom/lemonai/blob/main/provider_setting_result.json) schema structure.

This architectural separation allows Lemon AI to maintain a clean boundary between core platform metadata and user-customizable third-party integrations. While [`platform.json`](https://github.com/hexdocom/lemonai/blob/main/platform.json) defines the application’s global settings, the provider settings schema handles the dynamic, per-user search provider configurations that drive the platform’s extensible search capabilities.

## Summary

- **Schema Location**: The provider settings schema is defined in [`public/schemas/provider_setting_result.json`](https://github.com/hexdocom/lemonai/blob/main/public/schemas/provider_setting_result.json) and referenced by Swagger documentation in [`src/routers/search_provider_setting/setting.js`](https://github.com/hexdocom/lemonai/blob/main/src/routers/search_provider_setting/setting.js).
- **Dual-Model Storage**: Configuration data splits between `UserProviderConfig` (sensitive credentials in `base_config`) and `UserSearchSetting` (behavioral toggles like `include_date` and `cover_provider_search`).
- **API Conformance**: All responses from `/api/search_provider_setting` endpoints strictly follow the JSON schema structure, ensuring consistent data shapes across the platform.
- **Platform Separation**: Provider-specific settings remain isolated from the general platform configuration found in [`platform.json`](https://github.com/hexdocom/lemonai/blob/main/platform.json), enabling modular third-party integrations.

## Frequently Asked Questions

### Where is the provider settings schema defined in Lemon AI?

The schema is defined in the JSON file [`public/schemas/provider_setting_result.json`](https://github.com/hexdocom/lemonai/blob/main/public/schemas/provider_setting_result.json) located in the public schemas directory. This file serves as the canonical reference for the shape of provider configuration objects returned by the Search Provider Setting API endpoints.

### What properties are required when updating provider settings via the API?

The only strictly required property for creating a new provider setting is `provider_id` (integer), which links the configuration to a valid provider defined in [`provider.json`](https://github.com/hexdocom/lemonai/blob/main/provider.json). However, practical implementations typically require `api_key` and `endpoint` within the `base_config` object to establish functional API connectivity.

### How does Lemon AI handle sensitive API credentials within the schema structure?

Sensitive credentials are encapsulated within the `base_config` object and stored separately in the `UserProviderConfig` model. This architectural choice isolates authentication secrets from the `UserSearchSetting` model, which handles non-sensitive behavioral preferences, allowing for enhanced security controls such as field-level encryption on the credentials table.

### What distinguishes provider settings from the general platform configuration?

The [`platform.json`](https://github.com/hexdocom/lemonai/blob/main/platform.json) schema defines global, application-level settings such as platform name and logo, while [`provider_setting_result.json`](https://github.com/hexdocom/lemonai/blob/main/provider_setting_result.json) defines user-specific, third-party search provider configurations. The provider settings schema includes fields like `cover_provider_search` and `enable_enhanced_mode` that control search behavior, whereas the platform configuration manages the core application identity and global feature flags.