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.
An embedding environment (env) is one entry of Connections, Vector databases; default is the first. A route that reaches the vector database answers 400 when the environment is not set up, and 409 when the environment is assigned to another WordPress environment type (production, staging, development, local).
POST /kimaai/v1/embeddings/test-connection
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Tests a vector database’s connection with the given key, for Connections, Vector databases. A saved environment is tested with its stored key. Pinecone needs a key; Qdrant may be tested without one. Once the provider answers, the test checks where the content goes: with a serverHost, Pinecone’s index must answer; with a collection, Qdrant must have that collection; else the collection or index named after the site is created when it does not exist yet. With an id, the result and its time are kept for that database (option kimaai_connection_status) with a fingerprint of the provider, key, host and environment tested; it shows while the saved database has those values (GET /kimaai/v1/connection-status). The answer’s recorded says whether the result holds for the database as saved.
| Argument | Type | Required | Description |
|---|---|---|---|
provider | string | yes | The vector database: pinecone or qdrant. |
apiKey | string | no | The key to test, or the marker of a saved key. Required for Pinecone. |
id | string | no | The database the test is for, and whose stored key is tested when saved. |
serverHost | string | no | The database’s host: Qdrant’s address, or the Pinecone index’s host. |
collection | string | no | Qdrant: the collection the database uses; empty, the one named after the site. |
wpEnvironment | string | no | The WordPress environment type the database is meant for; this site’s by default. |
Returns: success and a message.
GET /kimaai/v1/embeddings/vectors
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
One page of the chunks KimaAI stored for an environment, from its own table.
| Argument | Type | Required | Description |
|---|---|---|---|
env | string | no | The embedding environment. Default default. |
page | integer | no | The page, from 1. Default 1. |
per_page | integer | no | Rows per page. Default 20. |
search | string | no | Text to search for. |
namespace | string | no | Only this namespace. |
orderby | string | no | The column to sort by. Default created_at. |
order | string | no | ASC or DESC. Default DESC. |
collection | string | no | Only this collection. |
post_id | integer | no | Only the chunks of this post. |
Returns: ok, items and total.
GET /kimaai/v1/embeddings/vectors/{id}
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
One stored chunk.
| Argument | Type | Required | Description |
|---|---|---|---|
id | string | yes | The vector’s ID. |
Returns: ok and item; 404 for an unknown ID.
POST /kimaai/v1/embeddings/delete
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Deletes vectors in the vector database and, once it confirmed, KimaAI’s rows of them. Fires kimaai_embedding_index_changed.
| Argument | Type | Required | Description |
|---|---|---|---|
env | string | no | The embedding environment. Default default. |
ids | array | no | The vectors’ IDs. |
delete_all | boolean | no | True to delete every vector of the namespace (Pinecone). |
Returns: ok, the database’s answer (provider) and deleted_local; 400 without IDs.
POST /kimaai/v1/embeddings/sync
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Syncs content into the vector database within the request: splits the posts into chunks, embeds them and uploads them. Checks the environment first and refuses with its failures when it cannot work.
| Argument | Type | Required | Description |
|---|---|---|---|
post_type | array | no | The post types to sync. Default ["post"]. |
post_id | integer | no | Only this post. |
post_ids | array | no | Only these posts. |
modified_after | string | no | Only posts modified after this date. |
limit | integer | no | At most this many posts; 0 for no limit. Default 0. |
dry_run | boolean | no | True to do everything but the upload. |
force | boolean | no | True to embed chunks again even when their content did not change. |
env | string | no | The embedding environment. |
Returns: The counts of the sync (embedded, skipped, failed, batches); 409 with the failed checks when the environment cannot work.
POST /kimaai/v1/embeddings/query
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Searches the vector database with a text, which is embedded first, or with a vector. Hits less similar than the database’s Min score are left out.
| Argument | Type | Required | Description |
|---|---|---|---|
env | string | no | The embedding environment. Default default. |
text | string | no | The text to search for. |
vector | array | no | A vector to search with instead. |
top | integer | no | The number of hits. Default: the database’s Max results. |
include_values | boolean | no | True to return the hits’ vectors. |
include_metadata | boolean | no | True to return the hits’ metadata. Default true. |
filter | object | no | A metadata filter in the database’s syntax. |
Returns: The database’s hits.
GET /kimaai/v1/embeddings/fetch
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Reads vectors from the vector database by ID.
| Argument | Type | Required | Description |
|---|---|---|---|
collection | string | no | The collection; the environment’s otherwise. |
namespace | string | no | The namespace; the environment’s otherwise. |
ids | array | yes | The vectors’ IDs. |
Returns: The database’s answer.
GET /kimaai/v1/embeddings/collections
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
The collections (indexes) of the vector database.
| Argument | Type | Required | Description |
|---|---|---|---|
env | string | no | The embedding environment. Default default. |
Returns: The database’s list.
POST /kimaai/v1/embeddings/collections
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Creates a collection (index) in the vector database.
| Argument | Type | Required | Description |
|---|---|---|---|
env | string | no | The embedding environment. Default default. |
name | string | yes | The collection’s name. |
dimension | integer | no | The vectors’ dimension; it must match the embedding model. Default 1536. |
metric | string | no | The distance metric. Default cosine. |
cloud | string | no | The cloud, for Pinecone. |
region | string | no | The region, for Pinecone. |
shard_number | integer | no | Shards, for Qdrant. |
replication_factor | integer | no | Replicas, for Qdrant. |
Returns: The database’s answer.
DELETE /kimaai/v1/embeddings/collections/{name}
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Deletes a collection (index) in the vector database, with every vector in it. Fires kimaai_embedding_index_changed.
| Argument | Type | Required | Description |
|---|---|---|---|
name | string | yes | The collection’s name. |
env | string | no | The embedding environment. Default default. |
Returns: The database’s answer.
GET /kimaai/v1/embeddings/stats
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
The vector database’s statistics of a collection.
| Argument | Type | Required | Description |
|---|---|---|---|
env | string | no | The embedding environment. Default default. |
collection | string | no | The collection; the environment’s otherwise. |
Returns: The database’s statistics.
GET /kimaai/v1/embeddings/health
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Checks an environment: its settings, the embedding model, the database’s collection and its dimension.
| Argument | Type | Required | Description |
|---|---|---|---|
env | string | no | The embedding environment. Default default. |
Returns: The checks with their status and an overall status.
GET /kimaai/v1/embeddings/sync/status
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
The progress of a sync that runs in the background.
| Argument | Type | Required | Description |
|---|---|---|---|
batch_id | string | yes | The sync, as /embeddings/sync/enqueue returned it. |
Returns: The batch and its status; 400 without batch_id.
GET /kimaai/v1/embeddings/logs
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
The log lines of background syncs.
| Argument | Type | Required | Description |
|---|---|---|---|
batch_id | string | no | Only this sync. |
post_id | integer | no | Only this post. |
after_id | integer | no | Only lines after this one, to follow a running sync. |
limit | integer | no | At most this many lines. Default 200. |
Returns: The log lines.
POST /kimaai/v1/embeddings/sync/enqueue
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Schedules a sync that runs in the background (Action Scheduler), in batches. Checks the environment first, as the sync does.
| Argument | Type | Required | Description |
|---|---|---|---|
post_type | array | no | The post types to sync. Default ["post"]. |
post_id | integer | no | Only this post. |
post_ids | array | no | Only these posts. |
modified_after | string | no | Only posts modified after this date. |
per_page | integer | no | Posts per batch, at most 200. Default 25. |
limit | integer | no | At most this many posts; 0 for no limit. Default 0. |
force | boolean | no | True to embed chunks again even when their content did not change. |
env | string | no | The embedding environment. |
Returns: ok, the batch_id and what it scheduled; 409 with the failed checks when the environment cannot work.
GET /kimaai/v1/embeddings/posts
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
One page of posts of a type with their sync state, for the knowledge base’s content list.
| Argument | Type | Required | Description |
|---|---|---|---|
env | string | no | The embedding environment. Default default. |
post_type | string | no | The post type. Default post. |
page | integer | no | The page, from 1. Default 1. |
per_page | integer | no | Posts per page. Default 20. |
search | string | no | Text to search for. |
orderby | string | no | The field to sort by. Default date. |
order | string | no | ASC or DESC. Default DESC. |
lang | string | no | Only posts in this language, for multilingual sites. |
Returns: The posts with their state, total and total_pages.
GET /kimaai/v1/embeddings/sources
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
The kinds of content the knowledge base can index (kimaai_embedding_supported_sources).
No arguments.
Returns: ok and items.
GET /kimaai/v1/embeddings/post-status
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
Whether one post is synced in an environment: its chunks, how many were uploaded or failed, and when.
| Argument | Type | Required | Description |
|---|---|---|---|
post_id | integer | yes | The post. |
env | string | no | The embedding environment. Default default. |
Returns: ok, post_id, env_id, collection, namespace, synced and stats; 400 without post_id.
GET /kimaai/v1/embeddings/languages
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
The languages of a multilingual site (WPML or Polylang), for the language picker.
No arguments.
Returns: provider, current, default and languages.
GET /kimaai/v1/embeddings/envs
- Access: internal
- Permission: an administrator (
manage_options) - Tier: premium
- Feature: none
The embedding environments, for the pickers of the admin.
No arguments.
Returns: ok, the site’s wp_environment and the environments as options.