> For the complete documentation index, see [llms.txt](https://docs.searchcitrus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.searchcitrus.com/cloud-hosted-citrus/api-reference.md).

# API Reference

It doesn't matter where your app is running - web, mobile, desktop, etc. As long as you can make HTTP requests, you can use citrus! If you want to use citrus locally with your app, please check out the [Python package documentation!](/quick-start.md)

## **Create Index**

Creates an index with the specified configuration.

* **URL:** `https://sgp2gcssi7.execute-api.us-west-2.amazonaws.com/prod/create-index`
* **Method:** `POST`
* **Headers:**
  * `x-api-key` - Your API key
* **Body:**

```json
{
    "index_name": string,
    "max_elements": int,
    "allow_replace_deleted": boolean,
    "M": int,
    "ef_construction": int
}
```

* **Parameters:**
  * `index_name` (string, required): The name of the index to be created.
  * `max_elements` (int, optional): The maximum number of elements the index can hold (default is 1000). Increases automatically when more vectors are inserted.
  * `allow_replace_deleted` (boolean, optional): Whether to allow replacing deleted elements (default is true).
  * `M` (int, optional): Parameter M used for index construction (default is 64).
  * `ef_construction` (int, optional): Parameter ef\_construction used for index construction (default is 200).

## **Insert Elements**

Inserts an element with its associated data into the specified index.

* **URL:** `https://sgp2gcssi7.execute-api.us-west-2.amazonaws.com/prod/insert`
* **Method:** `POST`
* **Headers:**
  * `x-api-key` - Your API key
* **Body:**

```json
{
    "index_name": string,
    "elements": [{
        "id": string,
        "text": string,
        "embedding": OpenAI embedding,
        "metadata": json
    }]
}
```

* **Parameters:**
  * `index_name` (string, required): The name of the index where the elements will be inserted.
  * `elements` (array of objects, required): An array containing the element details.
    * `id` (string, required): The unique identifier for the element.
    * `text` (string, optional): The text associated with the element.
    * `embedding` (vector, required): The vector embedding.
    * `metadata` (JSON, optional): Additional metadata in JSON format associated with the element.

**Notes:**

* The `index_name` should match the name of an existing index.
* For the insert request, providing an `embedding` with the element is required, while the `text` field is optional and can be omitted.
* Make sure to replace use your API key for sending any request.

## **Search Elements**

Performs semantic search on the specified index using query vectors.

* **URL:** `https://sgp2gcssi7.execute-api.us-west-2.amazonaws.com/prod/search`
* **Method:** `POST`
* **Headers:**
  * `x-api-key` - Your API key
* **Body:**

```json
{
    "index_name": string,
    "query_vectors": (list of embeddings to run semantic search),
    "top_k": (int) (default 10)
}
```

* **Parameters:**
  * `index_name` (string, required): The name of the index to perform the search on.
  * `query_vectors` (list of embeddings, required): The list of embeddings representing the query vectors for semantic search. For example, provide a list containing one vector to run semantic search against that vector only.
  * `top_k` (int, optional): The number of top results to return (default is 10).

**Notes:**

* The `index_name` should match the name of an existing index.
* The `top_k` parameter specifies the number of top search results to be returned (default is 10).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.searchcitrus.com/cloud-hosted-citrus/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.