API Reference

Integrating cloud hosted citrus is as simple as sending a bunch of HTTP requests.

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!

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:

{
    "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:

{
    "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:

{
    "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).