Syncing

Beta

Index V2 is in beta. All endpoints are available under client.beta.* in the SDK and may change before GA.

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.

Trigger a sync

Python

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

TypeScript

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

Note

Only one sync can run at a time for a given index. If a sync is already in progress, the API returns 409 Conflict.

Typical workflow

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

Python

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)

TypeScript

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

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

TypeScript

// 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

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

TypeScript

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