Collections API

The Collections API allows you to manage collections for organizing your documents. Collections help group related documents together for better organization and access control.

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

Create Collection

Create a new collection for organizing documents.

Endpoint: POST /collections

Request Body

Field	Type	Required	Description
name	string	Yes	Name of the collection
description	string	No	Description of the collection
is_private	boolean	No	Whether the collection is private (default: false)
company_id	string (UUID)	Yes	The ID of the company

Example Requests

curl -X POST "https://api.aloochat.ai/api/public/collections" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Technical Documentation",
    "description": "Collection for all technical documents and guides",
    "is_private": false,
    "company_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

const collectionData = {
  name: 'Technical Documentation',
  description: 'Collection for all technical documents and guides',
  is_private: false,
  company_id: '123e4567-e89b-12d3-a456-426614174000'
};
 
const response = await fetch('https://api.aloochat.ai/api/public/collections', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(collectionData)
});
 
const newCollection = await response.json();
console.log('Created collection:', newCollection);

import requests
 
url = "https://api.aloochat.ai/api/public/collections"
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
 
collection_data = {
    "name": "Technical Documentation",
    "description": "Collection for all technical documents and guides",
    "is_private": False,
    "company_id": "123e4567-e89b-12d3-a456-426614174000"
}
 
response = requests.post(url, headers=headers, json=collection_data)
new_collection = response.json()
print('Created collection:', new_collection)

Example Response

{
  "id": "456e7890-e89b-12d3-a456-426614174001",
  "name": "Technical Documentation",
  "description": "Collection for all technical documents and guides",
  "is_private": false,
  "company_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_by_id": "789e1234-e89b-12d3-a456-426614174002",
  "vector_namespace": "tech_docs_456e7890",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "document_count": 0
}

List Collections

Retrieve a paginated list of all collections for your company.

Endpoint: GET /collections

Parameters

Parameter	Type	Required	Description
skip	integer	No	Number of items to skip (default: 0)
limit	integer	No	Number of items to return (default: 100, max: 1000)

Example Requests

curl -X GET "https://api.aloochat.ai/api/public/collections?limit=20&skip=0" \
  -H "x-api-key: your_api_key_here"

const response = await fetch('https://api.aloochat.ai/api/public/collections?limit=20&skip=0', {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const collections = await response.json();
console.log('Collections:', collections);

import requests
 
url = "https://api.aloochat.ai/api/public/collections"
headers = {"x-api-key": "your_api_key_here"}
params = {"limit": 20, "skip": 0}
 
response = requests.get(url, headers=headers, params=params)
collections = response.json()
print('Collections:', collections)

Example Response

[
  {
    "id": "456e7890-e89b-12d3-a456-426614174001",
    "name": "Technical Documentation",
    "description": "Collection for all technical documents and guides",
    "is_private": false,
    "company_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_by_id": "789e1234-e89b-12d3-a456-426614174002",
    "vector_namespace": "tech_docs_456e7890",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "document_count": 15
  }
]

Get Collection

Retrieve a specific collection by ID.

Endpoint: GET /collections/{collectionId}

Parameters

Parameter	Type	Required	Description
collectionId	string (UUID)	Yes	The ID of the collection

Example Requests

curl -X GET "https://api.aloochat.ai/api/public/collections/456e7890-e89b-12d3-a456-426614174001" \
  -H "x-api-key: your_api_key_here"

const collectionId = "456e7890-e89b-12d3-a456-426614174001";
const response = await fetch(`https://api.aloochat.ai/api/public/collections/${collectionId}`, {
  method: 'GET',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const collection = await response.json();
console.log('Collection:', collection);

import requests
 
collection_id = "456e7890-e89b-12d3-a456-426614174001"
url = f"https://api.aloochat.ai/api/public/collections/{collection_id}"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.get(url, headers=headers)
collection = response.json()
print('Collection:', collection)

Update Collection

Update an existing collection.

Endpoint: PUT /collections/{collectionId}

Parameters

Parameter	Type	Required	Description
collectionId	string (UUID)	Yes	The ID of the collection to update

Request Body

All fields are optional for updates:

Field	Type	Required	Description
name	string	No	New name for the collection
description	string	No	New description for the collection
is_private	boolean	No	Whether the collection should be private

Example Requests

curl -X PUT "https://api.aloochat.ai/api/public/collections/456e7890-e89b-12d3-a456-426614174001" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Technical Documentation",
    "description": "Updated collection for technical documents and API guides",
    "is_private": true
  }'

const collectionId = "456e7890-e89b-12d3-a456-426614174001";
const updateData = {
  name: 'Updated Technical Documentation',
  description: 'Updated collection for technical documents and API guides',
  is_private: true
};
 
const response = await fetch(`https://api.aloochat.ai/api/public/collections/${collectionId}`, {
  method: 'PUT',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateData)
});
 
const updatedCollection = await response.json();
console.log('Updated collection:', updatedCollection);

import requests
 
collection_id = "456e7890-e89b-12d3-a456-426614174001"
url = f"https://api.aloochat.ai/api/public/collections/{collection_id}"
 
update_data = {
    "name": "Updated Technical Documentation",
    "description": "Updated collection for technical documents and API guides",
    "is_private": True
}
 
headers = {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
}
 
response = requests.put(url, headers=headers, json=update_data)
updated_collection = response.json()
print('Updated collection:', updated_collection)

Delete Collection

Delete a collection. Note that this will also affect any documents associated with the collection.

Endpoint: DELETE /collections/{collectionId}

Parameters

Parameter	Type	Required	Description
collectionId	string (UUID)	Yes	The ID of the collection to delete

Example Requests

curl -X DELETE "https://api.aloochat.ai/api/public/collections/456e7890-e89b-12d3-a456-426614174001" \
  -H "x-api-key: your_api_key_here"

const collectionId = "456e7890-e89b-12d3-a456-426614174001";
const response = await fetch(`https://api.aloochat.ai/api/public/collections/${collectionId}`, {
  method: 'DELETE',
  headers: {
    'x-api-key': 'your_api_key_here'
  }
});
 
const result = await response.json();
console.log('Delete result:', result);

import requests
 
collection_id = "456e7890-e89b-12d3-a456-426614174001"
url = f"https://api.aloochat.ai/api/public/collections/{collection_id}"
headers = {"x-api-key": "your_api_key_here"}
 
response = requests.delete(url, headers=headers)
result = response.json()
print('Delete result:', result)

Example Response

{
  "status": "success"
}

Error Responses

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

200 - Success
201 - Created successfully
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": "Collection not found"
}

Overview Data Categories