---
kind: rest
area: settings-admin
tier: free
summary: The routes of the settings, the setup wizard, the admin colour mode, the AI connection test and the log viewer.
---

# Settings and admin REST routes

The routes live under `/wp-json/kimaai/v1/`. A call from a logged-in browser sends the WordPress REST nonce, as every WordPress REST call does; a script uses an application password. A route that names a feature is registered only while that feature is not hidden (`app/Features/Features.php`).

Each route says its access. Internal: the route serves KimaAI's own admin screens or chat widget and may change or go away in any release without notice, so code outside KimaAI should not call it. Public: the route keeps its path, its arguments and its answer across releases, and changes only after a deprecation.

The settings pages save through WordPress's own `/wp/v2/settings` route (option `kimaai_options`, secrets masked), not through a route of this page.

## GET /kimaai/v1/admin-theme

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

The colour mode of KimaAI's admin screens for the current user.

No arguments.

Returns: `theme`, `light` or `dark` (stored per user).

## POST /kimaai/v1/admin-theme

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Stores the colour mode of KimaAI's admin screens for the current user.

| Argument | Type   | Required | Description        |
| -------- | ------ | -------- | ------------------ |
| `theme`  | string | yes      | `light` or `dark`. |

Returns: The stored theme.

## GET /kimaai/v1/settings-schema

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

The schema the settings pages are drawn from: KimaAI's settings files and those add-ons add through `kimaai_settings_schema_files`, without hidden features.

No arguments.

Returns: The schema.

## GET /kimaai/v1/settings-export

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Exports all settings, KimaAI's and the add-ons' with an option of their own, for Import and export in the settings. Secrets (API keys, tokens, signing secrets) are always blank.

No arguments.

Returns: `plugin`, `format`, `exported_at`, `schema_hash`, `options` (by option name) and `meta`.

## POST /kimaai/v1/settings-import

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Imports settings: an export, or a map of option names to values in the JSON body. Each known option is sanitised against its schema and replaces the stored one; secrets left blank keep the stored ones.

No arguments.

Returns: `ok` and `results` (`updated`, `skipped`, `unknown_keys`); 400 for a body that is not JSON.

## GET /kimaai/v1/wizard/config

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

The steps of the setup wizard.

No arguments.

Returns: The wizard's configuration.

## GET /kimaai/v1/wizard/state

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Whether the setup wizard was completed.

No arguments.

Returns: The wizard's state.

## POST /kimaai/v1/wizard/complete

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Marks the setup wizard as completed.

No arguments.

Returns: The wizard's state.

## POST /kimaai/v1/wizard/reset

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Marks the setup wizard as not completed, so it shows again.

No arguments.

Returns: The wizard's state.

## GET /kimaai/v1/connection-status

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

The last connection test of each AI environment and vector database that still holds for it as saved, by list (`aiServices.aiEnvs`, `embedding.embedEnvs`) and id: `status` (`ok` or `fail`), `testedAt` and `error`. The admin reads it again after saving a list of environments.

## POST /kimaai/v1/test-connection

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Tests an AI provider's connection with the given key, for Connections, AI services. A saved environment is tested with its stored key, which never goes back to the browser. With an `id`, the result and its time are kept for that environment (option `kimaai_connection_status`) with a fingerprint of the provider, key and address tested; it shows while the saved environment has those values (`GET /kimaai/v1/connection-status`). The answer's `recorded` says whether the result holds for the environment as saved.

| Argument   | Type   | Required | Description                                                                 |
| ---------- | ------ | -------- | --------------------------------------------------------------------------- |
| `provider` | string | yes      | The provider: `openai`, `openrouter` or `ollama`.                           |
| `apiKey`   | string | yes      | The key to test, or the marker of a saved key.                              |
| `endpoint` | string | no       | The provider's address, for Ollama.                                         |
| `id`       | string | no       | The environment the test is for, and whose stored key is tested when saved. |

Returns: `success` and a `message`.

## GET /kimaai/v1/logs/files

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

The log files of KimaAI's logger.

No arguments.

Returns: `files` and `activeFile`.

## GET /kimaai/v1/logs/content

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

The content of one log file.

| Argument | Type   | Required | Description                                                               |
| -------- | ------ | -------- | ------------------------------------------------------------------------- |
| `file`   | string | no       | A log file's name, as `/logs/files` lists it; the active file without it. |

Returns: `file`, `content` and `exists`.

## POST /kimaai/v1/logs/clear

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Empties one log file.

| Argument | Type   | Required | Description                                                               |
| -------- | ------ | -------- | ------------------------------------------------------------------------- |
| `file`   | string | no       | A log file's name, as `/logs/files` lists it; the active file without it. |

Returns: The cleared file's state; 400 for an invalid file name.

## DELETE /kimaai/v1/logs/file

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Deletes one log file.

| Argument | Type   | Required | Description                                   |
| -------- | ------ | -------- | --------------------------------------------- |
| `file`   | string | yes      | A log file's name, as `/logs/files` lists it. |

Returns: `deleted`, `files` and `activeFile`.

## POST /kimaai/v1/logs/clear-all

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Empties every log file.

No arguments.

Returns: `files` and `activeFile`.

## DELETE /kimaai/v1/logs/all

- Access: internal
- Permission: an administrator (`manage_options`)
- Tier: free
- Feature: none

Deletes every log file.

No arguments.

Returns: `files` and `activeFile`.
