# 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!](https://docs.searchcitrus.com/quick-start)

## **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).