Syncing

Guide

Index V2 (Beta)

Re-sync an index after adding, updating, or removing files in the source directory.

Overview

After you add, update, or remove files in a directory, you need to sync the index to reflect those changes. Syncing re-parses changed files and re-exports updated chunks to the vector store.

The initial sync is triggered automatically when you create an index. Use the sync endpoint for subsequent updates.

await client.beta.indexes.sync("<your-index-id>")

await client.beta.indexes.sync("<your-index-id>");

The sync runs asynchronously. Poll the index status to know when it completes (same pattern as the getting started guide).

Typical workflow

Upload new files or remove outdated files from the directory.
Call the sync endpoint.
Poll the index status until it returns to ready.
Resume retrieval or chat.

Python
TypeScript

import asyncio

# Add a new file to the directory
with open("new-report.pdf", "rb") as f:
    file_obj = await client.files.create(file=f, purpose="user_data")

await client.beta.directories.files.add(
    directory_id,
    file_id=file_obj.id,
)

# Trigger a sync
await client.beta.indexes.sync(index_id)

# Wait for it to finish
while True:
    idx = await client.beta.indexes.get(index_id)
    status = idx.metadata["status"] if idx.metadata else "unknown"
    if status == "ready":
        print("Sync complete!")
        break
    elif status == "failed":
        print("Sync failed:", idx.metadata["error_message"])
        break
    await asyncio.sleep(2)

import fs from "fs";

// Add a new file
const fileObj = await client.files.create({
  file: fs.createReadStream("new-report.pdf"),
  purpose: "user_data",
});

await client.beta.directories.files.add(directoryId, {
  file_id: fileObj.id,
});

// Trigger a sync
await client.beta.indexes.sync(indexId);

// Wait for it to finish
while (true) {
  const idx = await client.beta.indexes.get(indexId);
  const status = (idx.metadata?.status as string) ?? "unknown";
  if (status === "ready") {
    console.log("Sync complete!");
    break;
  } else if (status === "failed") {
    console.error("Sync failed:", idx.metadata?.error_message);
    break;
  }
  await new Promise((r) => setTimeout(r, 2000));
}

Managing indexes

Get an index

Python
TypeScript

# Get an index by ID
idx = await client.beta.indexes.get("<your-index-id>")
print(f"{idx.id}: status={idx.metadata['status']}")

// Get an index by ID
const idx = await client.beta.indexes.get("<your-index-id>");
console.log(`${idx.id}: status=${idx.metadata?.status}`);

Delete an index

Deleting an index removes the sync and export configuration. The source directory and its files are not affected.

Python
TypeScript

await client.beta.indexes.delete("<your-index-id>")

await client.beta.indexes.delete("<your-index-id>");