---
kind: rest
area: embedding-search
tier: premium
summary: The routes of the knowledge base admin in KimaAI Pro, which sync content into the vector database, list, query and delete vectors and manage collections.
---

# Embeddings 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.

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. 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 | yes      | The key to test, or the marker of a saved key.                                    |
| `id`            | string | no       | The database the test is for, and whose stored key is tested when saved.          |
| `serverHost`    | string | no       | The database's host, for Qdrant.                                                  |
| `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.

| 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 `5`.                   |
| `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`.
