Lemon AI Provider Settings Schema: Platform Configuration Structure Explained

Lemon AI defines provider settings through a strict JSON schema located at 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 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.
• 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 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 structure. The Swagger specification references this schema using:

// 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 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 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 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:

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:

{
  "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:

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 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 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 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 and referenced by Swagger documentation in 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, 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 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. 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 schema defines global, application-level settings such as platform name and logo, while 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}