Documents API

The Documents API allows you to manage documents in your knowledge base. You can upload files, articles, and website content, search through documents, and manage document metadata.

Base URL

https://api.aloochat.ai/api/public

Authentication

All requests require an API key in the x-api-key header:

x-api-key: your_api_key_here

Endpoints

Get Document

Retrieve a specific document by ID.

Endpoint: GET /documents/{documentId}

Parameters

Parameter	Type	Required	Description
documentId	string (UUID)	Yes	The ID of the document

Example Requests

curl -X GET "https://api.aloochat.ai/api/public/documents/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: your_api_key_here"

const documentId = "123e4567-e89b-12d3-a456-426614174000";
const response = await fetch(`https://api.aloochat.ai/api/public/documents/${documentId}`, {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const document = await response.json();
console.log('Document:', document);

import requests
 
document_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/documents/{document_id}"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.get(url, headers=headers)
document = response.json()
print('Document:', document)

List Documents

Get a paginated list of documents with optional filtering.

Endpoint: POST /documents/list

Request Body

Field	Type	Required	Description
categories	array	No	Filter by categories
start_date	string (datetime)	No	Filter documents created after this date
end_date	string (datetime)	No	Filter documents created before this date
collection_id	string (UUID)	No	Filter by collection ID
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 10)

Example Requests

curl -X POST "https://api.aloochat.ai/api/public/documents/list" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": ["tech", "documentation"],
    "page": 1,
    "limit": 20,
    "collection_id": "456e7890-e89b-12d3-a456-426614174001"
  }'

const listParams = {
  categories: ['tech', 'documentation'],
  page: 1,
  limit: 20,
  collection_id: '456e7890-e89b-12d3-a456-426614174001'
};
 
const response = await fetch('https://api.aloochat.ai/api/public/documents/list', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(listParams)
});
 
const documents = await response.json();
console.log('Documents:', documents);

import requests
 
url = "https://api.aloochat.ai/api/public/documents/list"
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
 
list_params = {
    "categories": ["tech", "documentation"],
    "page": 1,
    "limit": 20,
    "collection_id": "456e7890-e89b-12d3-a456-426614174001"
}
 
response = requests.post(url, headers=headers, json=list_params)
documents = response.json()
print('Documents:', documents)

Search Documents

Search through documents using various search methods.

Endpoint: POST /documents/search

Request Body

Field	Type	Required	Description
query	string	Yes	Search query
search_method	object	Yes	Search method configuration
top_k	integer	No	Number of results to return (default: 4)
categories	array	Yes	Categories to search within
start_date	string (datetime)	No	Filter documents created after this date
end_date	string (datetime)	No	Filter documents created before this date
collection_id	string (UUID)	No	Filter by collection ID

Search Method Object

Field	Type	Required	Description
enable_vectorsearch	boolean	No	Enable vector search (default: true)
enable_elasticsearch	boolean	No	Enable Elasticsearch (default: true)
enable_mongosearch	boolean	No	Enable MongoDB search (default: true)

Example Requests

curl -X POST "https://api.aloochat.ai/api/public/documents/search" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "API documentation",
    "search_method": {
      "enable_vectorsearch": true,
      "enable_elasticsearch": true,
      "enable_mongosearch": true
    },
    "top_k": 5,
    "categories": ["tech", "documentation"]
  }'

const searchParams = {
  query: 'API documentation',
  search_method: {
    enable_vectorsearch: true,
    enable_elasticsearch: true,
    enable_mongosearch: true
  },
  top_k: 5,
  categories: ['tech', 'documentation']
};
 
const response = await fetch('https://api.aloochat.ai/api/public/documents/search', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(searchParams)
});
 
const searchResults = await response.json();
console.log('Search results:', searchResults);

import requests
 
url = "https://api.aloochat.ai/api/public/documents/search"
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
 
search_params = {
    "query": "API documentation",
    "search_method": {
        "enable_vectorsearch": True,
        "enable_elasticsearch": True,
        "enable_mongosearch": True
    },
    "top_k": 5,
    "categories": ["tech", "documentation"]
}
 
response = requests.post(url, headers=headers, json=search_params)
search_results = response.json()
print('Search results:', search_results)

Upload File

Upload a document file (PDF, DOCX) for processing.

Endpoint: POST /documents/upload/file

Form Data Parameters

Parameter	Type	Required	Description
file	file	Yes	PDF or DOCX file to upload
document_title	string	Yes	Title for the document
categories	string	No	JSON array of category strings
collection_id	string (UUID)	No	Collection ID to associate with the document

Example Requests

curl -X POST "https://api.aloochat.ai/api/public/documents/upload/file" \
  -H "x-api-key: your_api_key_here" \
  -F "file=@document.pdf" \
  -F "document_title=API Documentation" \
  -F "categories=[\"tech\", \"documentation\"]" \
  -F "collection_id=456e7890-e89b-12d3-a456-426614174001"

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('document_title', 'API Documentation');
formData.append('categories', JSON.stringify(['tech', 'documentation']));
formData.append('collection_id', '456e7890-e89b-12d3-a456-426614174001');
 
const response = await fetch('https://api.aloochat.ai/api/public/documents/upload/file', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here'
  },
  body: formData
});
 
const uploadResult = await response.json();
console.log('Upload result:', uploadResult);

import requests
 
url = "https://api.aloochat.ai/api/public/documents/upload/file"
headers = {"x-api-key": "your_api_key_here"}
 
files = {'file': open('document.pdf', 'rb')}
data = {
    'document_title': 'API Documentation',
    'categories': '["tech", "documentation"]',
    'collection_id': '456e7890-e89b-12d3-a456-426614174001'
}
 
response = requests.post(url, headers=headers, files=files, data=data)
upload_result = response.json()
print('Upload result:', upload_result)

Example Response

{
  "task_id": "task_123e4567-e89b-12d3-a456-426614174000",
  "document_id": "doc_456e7890-e89b-12d3-a456-426614174001",
  "status": "pending"
}

Upload Article

Upload plain text content as a document.

Endpoint: POST /documents/upload/article

Request Body

Field	Type	Required	Description
content	string	Yes	The article text content
document_title	string	Yes	Title for the document
categories	array	No	List of category strings
collection_id	string (UUID)	No	Collection ID to associate with the document

Example Requests

curl -X POST "https://api.aloochat.ai/api/public/documents/upload/article" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This is the content of the article...",
    "document_title": "Getting Started Guide",
    "categories": ["guide", "tutorial"],
    "collection_id": "456e7890-e89b-12d3-a456-426614174001"
  }'

const articleData = {
  content: 'This is the content of the article...',
  document_title: 'Getting Started Guide',
  categories: ['guide', 'tutorial'],
  collection_id: '456e7890-e89b-12d3-a456-426614174001'
};
 
const response = await fetch('https://api.aloochat.ai/api/public/documents/upload/article', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(articleData)
});
 
const uploadResult = await response.json();
console.log('Upload result:', uploadResult);

import requests
 
url = "https://api.aloochat.ai/api/public/documents/upload/article"
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
 
article_data = {
    "content": "This is the content of the article...",
    "document_title": "Getting Started Guide",
    "categories": ["guide", "tutorial"],
    "collection_id": "456e7890-e89b-12d3-a456-426614174001"
}
 
response = requests.post(url, headers=headers, json=article_data)
upload_result = response.json()
print('Upload result:', upload_result)

Upload Website

Upload content from a website URL.

Endpoint: POST /documents/upload/website

Request Body

Field	Type	Required	Description
url	string	Yes	Website URL to scrape
document_title	string	Yes	Title for the document
categories	array	No	List of category strings
collection_id	string (UUID)	No	Collection ID to associate with the document

Example Requests

curl -X POST "https://api.aloochat.ai/api/public/documents/upload/website" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/documentation",
    "document_title": "External Documentation",
    "categories": ["external", "reference"],
    "collection_id": "456e7890-e89b-12d3-a456-426614174001"
  }'

const websiteData = {
  url: 'https://example.com/documentation',
  document_title: 'External Documentation',
  categories: ['external', 'reference'],
  collection_id: '456e7890-e89b-12d3-a456-426614174001'
};
 
const response = await fetch('https://api.aloochat.ai/api/public/documents/upload/website', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(websiteData)
});
 
const uploadResult = await response.json();
console.log('Upload result:', uploadResult);

import requests
 
url = "https://api.aloochat.ai/api/public/documents/upload/website"
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
 
website_data = {
    "url": "https://example.com/documentation",
    "document_title": "External Documentation",
    "categories": ["external", "reference"],
    "collection_id": "456e7890-e89b-12d3-a456-426614174001"
}
 
response = requests.post(url, headers=headers, json=website_data)
upload_result = response.json()
print('Upload result:', upload_result)

Update Document

Update an existing document’s metadata or content.

Endpoint: PUT /documents/{documentId}

Parameters

Parameter	Type	Required	Description
documentId	string (UUID)	Yes	The ID of the document to update

Request Body

All fields are optional for updates:

Field	Type	Required	Description
document_title	string	No	New title for the document
content	string	No	New content for the document
categories	array	No	New list of categories
collection_id	string (UUID)	No	New collection ID

Example Requests

curl -X PUT "https://api.aloochat.ai/api/public/documents/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "document_title": "Updated API Documentation",
    "categories": ["tech", "documentation", "updated"]
  }'

const documentId = "123e4567-e89b-12d3-a456-426614174000";
const updateData = {
  document_title: 'Updated API Documentation',
  categories: ['tech', 'documentation', 'updated']
};
 
const response = await fetch(`https://api.aloochat.ai/api/public/documents/${documentId}`, {
  method: 'PUT',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateData)
});
 
const updateResult = await response.json();
console.log('Update result:', updateResult);

import requests
 
document_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/documents/{document_id}"
 
update_data = {
    "document_title": "Updated API Documentation",
    "categories": ["tech", "documentation", "updated"]
}
 
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
 
response = requests.put(url, headers=headers, json=update_data)
update_result = response.json()
print('Update result:', update_result)

Delete Document

Delete a document from the knowledge base.

Endpoint: DELETE /documents/{documentId}

Parameters

Parameter	Type	Required	Description
documentId	string (UUID)	Yes	The ID of the document to delete

Example Requests

curl -X DELETE "https://api.aloochat.ai/api/public/documents/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: your_api_key_here"

const documentId = "123e4567-e89b-12d3-a456-426614174000";
const response = await fetch(`https://api.aloochat.ai/api/public/documents/${documentId}`, {
  method: 'DELETE',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const deleteResult = await response.json();
console.log('Delete result:', deleteResult);

import requests
 
document_id = "123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/documents/{document_id}"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.delete(url, headers=headers)
delete_result = response.json()
print('Delete result:', delete_result)

Check Task Status

Check the status of a document processing task.

Endpoint: GET /documents/task/{taskId}

Parameters

Parameter	Type	Required	Description
taskId	string (UUID)	Yes	The ID of the task to check

Example Requests

curl -X GET "https://api.aloochat.ai/api/public/documents/task/task_123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: your_api_key_here"

const taskId = "task_123e4567-e89b-12d3-a456-426614174000";
const response = await fetch(`https://api.aloochat.ai/api/public/documents/task/${taskId}`, {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const taskStatus = await response.json();
console.log('Task status:', taskStatus);

import requests
 
task_id = "task_123e4567-e89b-12d3-a456-426614174000"
url = f"https://api.aloochat.ai/api/public/documents/task/{task_id}"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.get(url, headers=headers)
task_status = response.json()
print('Task status:', task_status)

Example Response

{
  "task_id": "task_123e4567-e89b-12d3-a456-426614174000",
  "document_id": "doc_456e7890-e89b-12d3-a456-426614174001",
  "status": "completed",
  "error": null,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:32:15Z"
}

Check Document Similarity

Check similarity between documents to avoid duplicates.

Endpoint: POST /documents/check-similarity

Request Body

Field	Type	Required	Description
document	string	Yes	Document content to check
customer_id	string	Yes	Customer ID for comparison
similarity	number	No	Similarity threshold (0.0-1.0, default: 0.9)

Example Requests

curl -X POST "https://api.aloochat.ai/api/public/documents/check-similarity" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "This is the content to check for similarity...",
    "customer_id": "123e4567-e89b-12d3-a456-426614174000",
    "similarity": 0.85
  }'

const similarityCheck = {
  document: 'This is the content to check for similarity...',
  customer_id: '123e4567-e89b-12d3-a456-426614174000',
  similarity: 0.85
};
 
const response = await fetch('https://api.aloochat.ai/api/public/documents/check-similarity', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(similarityCheck)
});
 
const similarityResult = await response.json();
console.log('Similarity result:', similarityResult);

import requests
 
url = "https://api.aloochat.ai/api/public/documents/check-similarity"
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
 
similarity_check = {
    "document": "This is the content to check for similarity...",
    "customer_id": "123e4567-e89b-12d3-a456-426614174000",
    "similarity": 0.85
}
 
response = requests.post(url, headers=headers, json=similarity_check)
similarity_result = response.json()
print('Similarity result:', similarity_result)

Get Knowledge Base Stats

Get statistics about the knowledge base.

Endpoint: GET /documents/stats

Example Requests

curl -X GET "https://api.aloochat.ai/api/public/documents/stats" \
  -H "x-api-key: your_api_key_here"

const response = await fetch('https://api.aloochat.ai/api/public/documents/stats', {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const stats = await response.json();
console.log('Knowledge base stats:', stats);

import requests
 
url = "https://api.aloochat.ai/api/public/documents/stats"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.get(url, headers=headers)
stats = response.json()
print('Knowledge base stats:', stats)

Error Responses

The API uses standard HTTP status codes to indicate success or failure:

200 - Success
201 - Created successfully
202 - Accepted (for async operations)
400 - Bad request (invalid parameters)
401 - Unauthorized (invalid API key)
403 - Forbidden (insufficient permissions)
404 - Not found
500 - Internal server error

Error responses include a JSON object with error details:

{
  "detail": "Document not found"
}

Data Categories Companies