Skip to main content
The apicentric.json file is the main configuration file for Apicentric. It defines global settings for AI code generation and the API simulator.

​
Location

By default, Apicentric looks for apicentric.json in your project root directory.

​
Creating a configuration file

You can generate a default configuration file using the CLI: 
apicentric init
This creates an apicentric.json file with sensible defaults that you can customize for your project.

​
Configuration structure

The configuration file uses JSON format with two main sections: ai and simulator.

​
Example configuration

{
  "ai": {
    "provider": "gemini",
    "api_key": "your-api-key-here",
    "model": "gemini-2.5-flash"
  },
  "simulator": {
    "enabled": true,
    "services_dir": "services",
    "port_range": {
      "start": 9000,
      "end": 9099
    },
    "db_path": "apicentric.db",
    "admin_port": null,
    "global_behavior": {
      "latency": null,
      "error_simulation": null,
      "rate_limiting": null
    }
  }
}

​
AI configuration

Configure AI-assisted code generation features.
​
ai
object
required
AI generation configuration
​
ai.provider
string
required
The AI provider to use for text generation.Options:
  • openai - Use OpenAI API
  • gemini - Use Google Gemini API
  • local - Use a local language model
​
ai.api_key
string
API key for the selected provider. Required for openai and gemini providers.For Gemini, you can also set the GEMINI_API_KEY environment variable instead of storing the key in the config file.
For security, consider using environment variables instead of storing API keys directly in configuration files.
​
ai.model
string
Model identifier for the AI provider.Examples:
  • OpenAI: gpt-4, gpt-3.5-turbo
  • Gemini: gemini-2.5-flash, gemini-pro
​
ai.model_path
string
Path to the local model when using the local provider. Required only for local models.

​
Simulator configuration

Configure the API simulator that runs your service definitions.
​
simulator
object
required
API simulator configuration
​
simulator.enabled
boolean
required
Whether the simulator is enabled. Set to true to activate the simulator.Default: false
​
simulator.services_dir
string
required
Directory containing service definition YAML files. The simulator watches this directory for changes.Default: services
​
simulator.port_range
object
required
Port range for automatic port assignment to services.
​
simulator.port_range.start
number
required
Starting port number for the range.Default: 8000
​
simulator.port_range.end
number
required
Ending port number for the range.Default: 8999
​
simulator.db_path
string
required
Path to SQLite database file for persistent storage of service state.Default: apicentric.db
​
simulator.admin_port
number
Port for the admin API server. If not specified, the admin API is disabled.Default: null (disabled)
​
simulator.global_behavior
object
Global behavior settings that apply to all services unless overridden.
​
simulator.global_behavior.latency
object
Simulate network latency for all endpoints.
​
simulator.global_behavior.latency.min_ms
number
required
Minimum latency in milliseconds.
​
simulator.global_behavior.latency.max_ms
number
required
Maximum latency in milliseconds.
​
simulator.global_behavior.error_simulation
object
Simulate random errors for testing error handling.
​
simulator.global_behavior.error_simulation.enabled
boolean
required
Enable error simulation.
​
simulator.global_behavior.error_simulation.rate
number
required
Error rate between 0.0 and 1.0 (e.g., 0.1 = 10% error rate).
​
simulator.global_behavior.error_simulation.status_codes
array
Array of HTTP status codes to return when simulating errors.Example: [500, 502, 503]
​
simulator.global_behavior.rate_limiting
object
Simulate rate limiting for all services.
​
simulator.global_behavior.rate_limiting.enabled
boolean
required
Enable rate limiting.
​
simulator.global_behavior.rate_limiting.requests_per_minute
number
required
Maximum number of requests allowed per minute.

​
Validation

Apicentric validates your configuration file when loading it. Common validation errors include:
  • Missing required API keys for the selected AI provider
  • Invalid port numbers (must be >= 1024)
  • Invalid JSON syntax
  • Missing required fields
If validation fails, you’ll see detailed error messages explaining what needs to be fixed.
Sensitive fields like API keys are automatically redacted when displaying configuration through the admin API.

​
Best practices

  1. Use environment variables for secrets - Store API keys in environment variables instead of committing them to version control
  2. Keep port ranges reasonable - Use port ranges that don’t conflict with other services on your system
  3. Enable global behaviors for testing - Use latency and error simulation to test your application’s resilience
  4. Use descriptive service directories - Organize your service definitions in a clear directory structure

Build docs developers (and LLMs) love

Get started for freeTalk to us