Delete a document from a given assistant

Overview

Delete a document from your AI assistant’s knowledge base using its external ID. This removes the document from both Ragie (AI platform) and your database, ensuring your assistant no longer uses this content. Use this endpoint to remove outdated, incorrect, or sensitive information from your AI’s knowledge.

Use Cases

Content Updates: Remove old versions before uploading new ones
Data Cleanup: Remove outdated or deprecated documentation
Compliance: Delete sensitive information that shouldn’t be in AI knowledge
Content Management: Remove documents that are no longer relevant
Error Correction: Delete incorrectly uploaded documents
Bulk Cleanup: Programmatically remove multiple outdated documents

Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

x-api-key: your_api_key_here

Path Parameters

Parameter	Type	Required	Description
`externalId`	string	Yes	The external ID you assigned when uploading

External ID: This is the same externalId you provided when uploading the document with POST /api/documents/assistant/raw.

Response Structure

Field	Type	Description
`status`	string	Deletion status (e.g., “deleted”)

Example Request

curl --request DELETE \
  'https://api.vambe.ai/api/documents/assistant/ext-product-faq-001' \
  --header 'x-api-key: your_api_key_here'

Example Response

{
  "status": "deleted"
}

Common Use Cases

1. Delete Single Document

const deleteDocument = async (externalId) => {
  const response = await fetch(
    `https://api.vambe.ai/api/documents/assistant/${externalId}`,
    {
      method: 'DELETE',
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const result = await response.json();

  if (result.status === 'deleted') {
    console.log(`✅ Document ${externalId} deleted successfully`);
  }

  return result;
};

2. Update Document (Delete + Upload)

const updateDocument = async (externalId, newContent, folderId) => {
  // 1. Delete old version
  await fetch(`https://api.vambe.ai/api/documents/assistant/${externalId}`, {
    method: 'DELETE',
    headers: {
      'x-api-key': 'your_api_key_here',
    },
  });

  console.log('Old version deleted');

  // 2. Upload new version with same external ID
  const response = await fetch(
    'https://api.vambe.ai/api/documents/assistant/raw',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify({
        content: newContent,
        fileName: 'updated-document.md',
        externalId: externalId, // Same ID for tracking
        folderId: folderId,
        icon: '📄',
      }),
    },
  );

  const result = await response.json();
  console.log('New version uploaded');

  return result;
};

3. Bulk Delete Documents

const bulkDeleteDocuments = async (externalIds) => {
  const results = [];

  for (const externalId of externalIds) {
    try {
      const response = await fetch(
        `https://api.vambe.ai/api/documents/assistant/${externalId}`,
        {
          method: 'DELETE',
          headers: {
            'x-api-key': 'your_api_key_here',
          },
        },
      );

      const result = await response.json();
      results.push({ externalId, success: true, status: result.status });

      console.log(`✅ Deleted: ${externalId}`);
    } catch (error) {
      results.push({ externalId, success: false, error: error.message });
      console.error(`❌ Failed to delete: ${externalId}`);
    }

    // Small delay to avoid rate limiting
    await new Promise((resolve) => setTimeout(resolve, 100));
  }

  console.log(
    `Deleted ${results.filter((r) => r.success).length} of ${externalIds.length} documents`,
  );

  return results;
};

4. Clean Up Old Documents

const cleanupOldDocuments = async (olderThanDays = 30) => {
  // Get all folders with documents
  const foldersResponse = await fetch(
    'https://api.vambe.ai/api/documents/assistant/folders',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const folders = await foldersResponse.json();

  // Find documents to delete (this would need metadata about age)
  // For example, if your external IDs include timestamps
  const oldDocumentIds = [];

  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - olderThanDays);

  // Your logic to identify old documents
  // e.g., external IDs with dates: 'doc-2024-01-15-product'

  // Delete old documents
  for (const externalId of oldDocumentIds) {
    await deleteDocument(externalId);
  }

  console.log(`Cleaned up ${oldDocumentIds.length} old documents`);
};

5. Safe Delete with Confirmation

const safeDeleteDocument = async (externalId) => {
  try {
    // Optional: Get folder info to show what's being deleted
    const foldersResponse = await fetch(
      'https://api.vambe.ai/api/documents/assistant/folders',
      {
        headers: { 'x-api-key': 'your_api_key_here' },
      },
    );

    const folders = await foldersResponse.json();

    // Find the document in folders (for confirmation)
    let foundDoc = null;
    for (const folder of folders) {
      foundDoc = folder.documents.find((d) => d.id === externalId);
      if (foundDoc) break;
    }

    if (foundDoc) {
      console.log(`About to delete: ${foundDoc.name}`);
    }

    // Delete
    const response = await fetch(
      `https://api.vambe.ai/api/documents/assistant/${externalId}`,
      {
        method: 'DELETE',
        headers: {
          'x-api-key': 'your_api_key_here',
        },
      },
    );

    const result = await response.json();
    console.log('✅ Document deleted');

    return result;
  } catch (error) {
    console.error('Delete failed:', error);
    throw error;
  }
};

What Gets Deleted

When you delete a document:

✅ Ragie Document: Removed from AI knowledge platform
✅ Database Record: Removed from knowledge_base_document table
✅ AI Knowledge: Assistant will no longer use this content
❌ Folder: The containing folder is NOT deleted
❌ Assistant Link: Assistant-folder link remains (only document removed)

Error Responses

Status Code	Description
400	Bad Request - Invalid external ID
401	Unauthorized - Invalid or missing API key
404	Not Found - Document not found
500	Internal Server Error - Something went wrong

Important Notes

Uses External ID: Delete by YOUR external ID, not Ragie’s internal ID
Permanent: Deletion is permanent and cannot be undone
Both Systems: Deletes from both Ragie and your database
Folder Intact: Only document is deleted, folder remains
Immediate Effect: AI will stop using this content immediately
Not Found OK: Deleting non-existent document returns 404

External ID Format

Your external ID can be any string:

✅ "product-guide-v2"
✅ "cms-article-12345"
✅ "faq-${Date.now()}"
✅ "user-manual-en"

Make sure to track these IDs in your system!

POST /api/documents/assistant/raw - Upload a new document
GET /api/documents/assistant/folders - List folders and documents
POST /api/documents/assistant/folders - Create folders

Best Practices

1. Track External IDs

// Keep a mapping of your documents
const documentRegistry = {
  'product-guide-v1': { uploaded: '2024-01-15', active: false },
  'product-guide-v2': { uploaded: '2024-09-30', active: true },
};

// Delete old version
await deleteDocument('product-guide-v1');

2. Confirm Before Delete

const confirmAndDelete = async (externalId, documentName) => {
  const confirmed = confirm(`Delete "${documentName}"?`);

  if (confirmed) {
    return await deleteDocument(externalId);
  }

  console.log('Deletion cancelled');
  return null;
};

3. Handle Not Found Gracefully

const safeDelete = async (externalId) => {
  try {
    return await deleteDocument(externalId);
  } catch (error) {
    if (error.status === 404) {
      console.log('Document already deleted or never existed');
      return { status: 'already_deleted' };
    }
    throw error;
  }
};

Headers

x-api-key

string

required

API key needed to authorize the request

Path Parameters

externalId

string

required

The external id of the document

Response

Document deleted successfully.

Knowledge Base

​Overview

​Use Cases

​Authentication

​Path Parameters

​Response Structure

​Example Request

​Example Response

​Common Use Cases

​1. Delete Single Document

​2. Update Document (Delete + Upload)

​3. Bulk Delete Documents

​4. Clean Up Old Documents

​5. Safe Delete with Confirmation

​What Gets Deleted

​Error Responses

​Important Notes

​External ID Format

​Related Endpoints

​Best Practices

​1. Track External IDs

​2. Confirm Before Delete

​3. Handle Not Found Gracefully

Headers

Path Parameters

Response

Overview

Use Cases

Authentication

Path Parameters

Response Structure

Example Request

Example Response

Common Use Cases

1. Delete Single Document

2. Update Document (Delete + Upload)

3. Bulk Delete Documents

4. Clean Up Old Documents

5. Safe Delete with Confirmation

What Gets Deleted

Error Responses

Important Notes

External ID Format

Related Endpoints

Best Practices

1. Track External IDs

2. Confirm Before Delete

3. Handle Not Found Gracefully