This document provides instructions on how to interact with the OpenAI Vector Store API endpoints and the Ragwalla equivalents which are supported by the OpenAI SDKs by simply setting the baseUrl when instantiating the class. All API endpoints are prefixed with /v1.

Authentication

All requests to the API must be authenticated. Include your API key in the Authorization header as a Bearer token.

Header: Authorization: Bearer YOUR_API_KEY

Endpoints

1. Modify a Vector Store

Updates the specified vector store by setting the values of the parameters passed.

HTTP Request
POST /v1/vector_stores/{vector_store_id}

Path Parameters
- vector_store_id (string, required): The ID of the vector store to modify.

Request Body
- name (string, optional): The new name for the vector store.
- metadata (object, optional): A set of up to 16 key-value pairs that can be attached to the vector store. Keys can be a maximum of 64 characters and values can be a maximum of 512 characters.
- expires_after (object, optional): The expiration policy for the vector store.
- anchor (string, required): The anchor for expiration. Must be last_active_at.
- days (integer, required): The number of days after the last activity until the vector store expires. Must be between 1 and 365.

Example Request

{
  "name": "Updated Store Name",
  "metadata": {
    "client_id": "client-5678",
    "environment": "production"
  },
  "expires_after": {
    "anchor": "last_active_at",
    "days": 30
  }
}

Successful Response (200 OK)
Returns the modified VectorStore object.

Example Response

{
  "id": "vs_abc123",
  "object": "vector_store",
  "created_at": 1699061776,
  "name": "Updated Store Name",
  "usage_bytes": 123456,
  "file_counts": {
    "in_progress": 0,
    "completed": 6,
    "failed": 0,
    "cancelled": 0,
    "total": 6
  },
  "status": "completed",
  "expires_after": {
    "anchor": "last_active_at",
    "days": 30
  },
  "expires_at": 1701653776,
  "last_active_at": 1699061776,
  "metadata": {
    "client_id": "client-5678",
    "environment": "production"
  }
}

2. Update a Vector Store File

Updates the specified vector store file by setting the values of the parameters passed.

HTTP Request
POST /v1/vector_stores/{vector_store_id}/files/{file_id}

Path Parameters
- vector_store_id (string, required): The ID of the vector store that the file belongs to.
- file_id (string, required): The ID of the file to update.

Request Body
- metadata (object, optional): A set of up to 16 key-value pairs to attach to the file. Keys can be a maximum of 64 characters and values can be a maximum of 512 characters.

Example Request

{
  "metadata": {
    "user_id": "user-abcd",
    "source": "manual_upload"
  }
}

Successful Response (200 OK)
Returns the modified VectorStoreFile object.

Example Response

{
  "id": "file_xyz456",
  "object": "vector_store.file",
  "usage_bytes": 12345,
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "completed",
  "last_error": null,
  "metadata": {
    "user_id": "user-abcd",
    "source": "manual_upload"
  }
}

3. Get Vector Store File Content

Retrieves the parsed content of a file from a vector store.

HTTP Request
GET /v1/vector_stores/{vector_store_id}/files/{file_id}/content

Path Parameters
- vector_store_id (string, required): The ID of the vector store that the file belongs to.
- file_id (string, required): The ID of the file.

Successful Response (200 OK)
Returns a paginated object containing the file's content.

Example Response

{
  "object": "vector_store.file_content.page",
  "data": [
    {
      "type": "text",
      "text": "This is the full text content of the file..."
    }
  ],
  "has_more": false,
  "next_page": null
}

4. Cancel a Vector Store File Batch

Cancels a file batch that is in_progress.

HTTP Request
POST /v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel

Path Parameters
- vector_store_id (string, required): The ID of the vector store that the file batch belongs to.
- batch_id (string, required): The ID of the file batch to cancel.

Successful Response (200 OK)
Returns the VectorStoreFileBatch object with a status of cancelling or cancelled.

Example Response

{
  "id": "vsfb_abc123",
  "object": "vector_store.file_batch",
  "created_at": 1699061776,
  "vector_store_id": "vs_abc123",
  "status": "cancelled",
  "file_counts": {
    "in_progress": 0,
    "completed": 3,
    "failed": 0,
    "cancelled": 12,
    "total": 15
  }
}

5. Search a Vector Store

Performs a semantic search on the content of a vector store.

HTTP Request
POST /v1/vector_stores/{vector_store_id}/search

Path Parameters
- vector_store_id (string, required): The ID of the vector store to search.

Request Body
- query (string, required): The text to search for.
- max_num_results (integer, optional, default: 10): The maximum number of results to return.
- filters (object, optional): A metadata object to filter results. Only chunks with matching metadata will be returned.

Example Request

{
  "query": "What is the new company policy on remote work?",
  "max_num_results": 5,
  "filters": {
    "document_type": "handbook"
  }
}

Successful Response (200 OK)
Returns a page of search results.

Example Response

{
  "object": "vector_store.search_results.page",
  "search_query": "What is the new company policy on remote work?",
  "data": [
    {
      "object": "vector_store.search_result",
      "type": "file_content",
      "file_id": "file_abc123",
      "chunk_id": "chunk_def456",
      "content": "...employees are expected to work from the office at least three days a week, effective next quarter...",
      "score": 0.912
    },
    {
      "object": "vector_store.search_result",
      "type": "file_content",
      "file_id": "file_abc123",
      "chunk_id": "chunk_ghi789",
      "content": "...requests for fully remote work arrangements must be approved by department heads...",
      "score": 0.874
    }
  ],
  "has_more": false
}