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

ArgumentTypeRequiredDescription
providerstringyesThe vector database: pinecone or qdrant.
apiKeystringnoThe key to test, or the marker of a saved key. Required for Pinecone.
idstringnoThe database the test is for, and whose stored key is tested when saved.
serverHoststringnoThe database’s host: Qdrant’s address, or the Pinecone index’s host.
collectionstringnoQdrant: the collection the database uses; empty, the one named after the site.
wpEnvironmentstringnoThe 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.

ArgumentTypeRequiredDescription
envstringnoThe embedding environment. Default default.
pageintegernoThe page, from 1. Default 1.
per_pageintegernoRows per page. Default 20.
searchstringnoText to search for.
namespacestringnoOnly this namespace.
orderbystringnoThe column to sort by. Default created_at.
orderstringnoASC or DESC. Default DESC.
collectionstringnoOnly this collection.
post_idintegernoOnly 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.

ArgumentTypeRequiredDescription
idstringyesThe 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.

ArgumentTypeRequiredDescription
envstringnoThe embedding environment. Default default.
idsarraynoThe vectors’ IDs.
delete_allbooleannoTrue 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.

ArgumentTypeRequiredDescription
post_typearraynoThe post types to sync. Default ["post"].
post_idintegernoOnly this post.
post_idsarraynoOnly these posts.
modified_afterstringnoOnly posts modified after this date.
limitintegernoAt most this many posts; 0 for no limit. Default 0.
dry_runbooleannoTrue to do everything but the upload.
forcebooleannoTrue to embed chunks again even when their content did not change.
envstringnoThe 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.

ArgumentTypeRequiredDescription
envstringnoThe embedding environment. Default default.
textstringnoThe text to search for.
vectorarraynoA vector to search with instead.
topintegernoThe number of hits. Default: the database’s Max results.
include_valuesbooleannoTrue to return the hits’ vectors.
include_metadatabooleannoTrue to return the hits’ metadata. Default true.
filterobjectnoA 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.

ArgumentTypeRequiredDescription
collectionstringnoThe collection; the environment’s otherwise.
namespacestringnoThe namespace; the environment’s otherwise.
idsarrayyesThe 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.

ArgumentTypeRequiredDescription
envstringnoThe 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.

ArgumentTypeRequiredDescription
envstringnoThe embedding environment. Default default.
namestringyesThe collection’s name.
dimensionintegernoThe vectors’ dimension; it must match the embedding model. Default 1536.
metricstringnoThe distance metric. Default cosine.
cloudstringnoThe cloud, for Pinecone.
regionstringnoThe region, for Pinecone.
shard_numberintegernoShards, for Qdrant.
replication_factorintegernoReplicas, 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.

ArgumentTypeRequiredDescription
namestringyesThe collection’s name.
envstringnoThe 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.

ArgumentTypeRequiredDescription
envstringnoThe embedding environment. Default default.
collectionstringnoThe 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.

ArgumentTypeRequiredDescription
envstringnoThe 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.

ArgumentTypeRequiredDescription
batch_idstringyesThe 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.

ArgumentTypeRequiredDescription
batch_idstringnoOnly this sync.
post_idintegernoOnly this post.
after_idintegernoOnly lines after this one, to follow a running sync.
limitintegernoAt 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.

ArgumentTypeRequiredDescription
post_typearraynoThe post types to sync. Default ["post"].
post_idintegernoOnly this post.
post_idsarraynoOnly these posts.
modified_afterstringnoOnly posts modified after this date.
per_pageintegernoPosts per batch, at most 200. Default 25.
limitintegernoAt most this many posts; 0 for no limit. Default 0.
forcebooleannoTrue to embed chunks again even when their content did not change.
envstringnoThe 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.

ArgumentTypeRequiredDescription
envstringnoThe embedding environment. Default default.
post_typestringnoThe post type. Default post.
pageintegernoThe page, from 1. Default 1.
per_pageintegernoPosts per page. Default 20.
searchstringnoText to search for.
orderbystringnoThe field to sort by. Default date.
orderstringnoASC or DESC. Default DESC.
langstringnoOnly 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.

ArgumentTypeRequiredDescription
post_idintegeryesThe post.
envstringnoThe 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.

What are your feelings