Vector Store API Reference

To interact with the Vector Store REST API, you must first obtain a JFrog ML Token. This token is used to authenticate your requests.

Obtaining a JFrog ML Token

  1. Generate a new JFrog ML Token with the following command to obtain a token, valid for 24 hours:
    curl --request POST 'https://grpc.qwak.ai/api/v1/authentication/qwak-api-key' \
         --header 'Content-Type: application/json' \
         --data '{"qwakApiKey": "<QWAK_API_KEY>"}'
    
  2. Export your JFrog ML Token as an environment variable in your terminal:
    export QWAK_TOKEN="YOUR_GENERATED_QWAK_TOKEN"
    

Making a Request

Use the following curl command template to send requests to the Vector Store. Replace <your-environment> with the name of your account, which can be found in the bottom left corner of the JFrog ML Dashboard, and <your operation payload as JSON> with the JSON payload of your operation as in the references below.

curl --location --request POST 'https://grpc.<your-environment>.qwak.ai/api/v1/vectors/upsert' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $QWAK_TOKEN" \
--data '<your operation payload as JSON>'

URL Structure

  • Base URL: https://grpc.<your-environment>.qwak.ai, replace <your-environment> with your specific account name.

Required Headers

  • Content-Type: Should always be application/json
  • Authorization: Use the bearer token format: Bearer <your_qwak_token>.
    Ensure the header is enclosed in double quotes (") when passing the QWAK_TOKEN as an environment variable.

📘

Before executing the curl command, ensure the QWAK_TOKEN environment variable is correctly set in your terminal with the value of your generated JFrog ML Token. This step is crucial for authenticating your requests to the Vector Store.


Vector Store Collection Operations

Search Similar Vectors

POST - /api/v1/vectors/search

Description - Searches for vectors similar to a reference vector within a specified collection.

Example Request Body:

{
  "collection_name": "your_collection_name",
  "reference_vector": {
    "element": [0.1, 0.2, 0.3]
  },
  "properties": ["property1", "property2"],
  "max_results": 5,
  "include_vector": true,
  "include_distance": true,
  "include_id": true,
  "tenant_id": "optional_tenant_id"
}

Example Response:

{
  "search_results": [
    {
      "vector": {"values": [0.1, 0.2, 0.3]},
      "distance": 0.01,
      "id": "vector_id"
    }
  ]
}


Upsert Vectors

POST - api/v1/vectors/upsert

Description - Inserts new vectors or updates existing ones within a specified collection.

Example Request Body:

{
  "collection_name": "your_collection_name",
  "vector": [
    {
      "id": "vector_id",
      "values": [0.1, 0.2, 0.3],
      "properties": {"property_name": "property_value"}
    }
  ]
}

Example Response:

{
  "num_affected": 1
}


Delete Vectors

POST - /api/v1/vectors/delete

Description - Deletes specified vectors from a collection.

Example Request Body:

{
  "collection_name": "your_collection_name",
  "vector_identifiers": [
    {"vector_id": "vector_id", "tenant_id": "optional_tenant_id"}
  ]
}

Example Response:

{
  "num_vectors_deleted": 1
}


Fetch Vector

GET - /api/v1/vectors/collections/{collection}/{id}

Description - Fetches a specific vector by ID from a collection.

Parameters:

  • collection: Name of the collection.
  • id: ID of the vector to fetch.
  • tenant_id: (Query parameter) Optional tenant ID.

Example Response:

{
  "vector": {
    "id": "vector_id",
    "values": [0.1, 0.2, 0.3],
    "properties": {"property_name": "property_value"}
  }
}


Get Vector Sample

POST - /api/v1/vectors/sample

Description - Retrieves a sample of vectors from a specified collection.

Example Request Body:

{
  "collection_name": "your_collection_name",
  "num_samples": 5,
  "include_vector": true,
  "tenant_id": "optional_tenant_id"
}

Example Response:

{
  "vectors": [
    {
      "id": "vector_id",
      "values": [0.1, 0.2, 0.3],
      "properties": {"property_name": "property_value"}
    }
  ]
}