Overview
DataBrain provides a RESTful API that allows developers to harness the power of Retrieval-Augmented Generation (RAG) technology. With our API, you can upload documents, create knowledge bases, and generate highly accurate, contextually relevant responses based on your data.
Our API is organized around REST principles. All requests should be made to the base URL https://api.databrain.ai/rag, using HTTPS, and will return JSON-encoded responses with standard HTTP response codes.
Document Management
Upload and manage your documents that will serve as sources for the RAG system.
Query Capabilities
Retrieve information from your documents using natural language queries.
Secure & Scalable
Enterprise-grade security with token-based authentication and scalable infrastructure.
Authentication
DataBrain API uses token-based authentication. You'll need to include your API token in the Authorization header for all requests.
Authorization Header
Authorization: Bearer YOUR_API_TOKEN
You can obtain your API token from the DataBrain Dashboard under API Settings. Keep your token secure and don't share it in publicly accessible areas such as GitHub or client-side code.
Document Management
DataBrain supports various document types including PDF, TXT, DOCX, MP3, and CSV files. Documents are processed and chunked automatically for optimal retrieval.
Upload Document
POSTUpload and process a document to be used as a knowledge source for RAG queries.
Endpoint
https://ai.goodbits.tech/api/rag/documents/upload
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| document | File | Yes | The document file to upload (PDF, TXT, CSV, DOCX, MP3) |
Response (201 Created)
{
"message": "Document processed successfully",
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "example.pdf",
"type": "pdf",
"chunks": 15
}
List Documents
GETRetrieve a list of all documents uploaded by the current user.
Endpoint
https://ai.goodbits.tech/api/rag/documents
Parameters
No parameters required.
Response (200 OK)
{
"documents": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "example1.pdf",
"type": "pdf",
"created_at": "2023-06-01T15:30:45Z"
},
{
"id": "123e4567-e89b-12d3-a456-426614174001",
"name": "example2.txt",
"type": "txt",
"created_at": "2023-06-02T10:15:30Z"
}
]
}
Documents List API
Retrieve detailed information about your documents with advanced filtering, pagination, and statistics. This API provides comprehensive management capabilities for all documents in your account.
List All Documents
GETRetrieve a paginated list of all documents with optional filtering and sorting capabilities.
Endpoint
https://ai.goodbits.tech/api/documents
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| per_page | Integer | No | Number of items per page (default: 15, max: 100) |
| search | String | No | Search by document name |
| type | String | No | Filter by document type (pdf, txt, docx, csv, etc) |
| batch_id | UUID | No | Filter by batch ID |
| status | String | No | Filter by processing status (queued, processing, completed, failed) |
| sort_by | String | No | Field to sort by (created_at, name, type) - default: created_at |
| sort_order | String | No | Sort order (asc, desc) - default: desc |
Example Request
GET https://ai.goodbits.tech/api/documents?per_page=20&search=contract&type=pdf&sort_by=name&sort_order=asc
Response (200 OK)
{
"success": true,
"data": [
{
"id": "9c8e7f6d-5a4b-3c2d-1e0f-123456789abc",
"name": "Contract 2024.pdf",
"type": "pdf",
"file_path": "documents/abc123.pdf",
"batch_id": "9c8e7f6d-5a4b-3c2d-1e0f-987654321xyz",
"batch_name": "Upload Batch 1",
"batch_status": "completed",
"processing_order": 1,
"processing_status": "completed",
"chunks_count": 25,
"vector_ids_count": 25,
"size": 2048576,
"mime_type": "application/pdf",
"created_at": "2025-10-09 10:30:00",
"updated_at": "2025-10-09 10:35:00",
"deleted_at": null
},
{
"id": "9c8e7f6d-5a4b-3c2d-1e0f-123456789def",
"name": "Contract Amendment.pdf",
"type": "pdf",
"file_path": "documents/def456.pdf",
"batch_id": "9c8e7f6d-5a4b-3c2d-1e0f-987654321xyz",
"batch_name": "Upload Batch 1",
"batch_status": "completed",
"processing_order": 2,
"processing_status": "completed",
"chunks_count": 12,
"vector_ids_count": 12,
"size": 1024000,
"mime_type": "application/pdf",
"created_at": "2025-10-09 10:32:00",
"updated_at": "2025-10-09 10:37:00",
"deleted_at": null
}
],
"pagination": {
"total": 150,
"per_page": 20,
"current_page": 1,
"last_page": 8,
"from": 1,
"to": 20
}
}
Get Document Details
GETRetrieve complete details about a specific document including content, metadata, batch information, and vector IDs.
Endpoint
https://ai.goodbits.tech/api/documents/{document_id}
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| document_id | UUID | Yes | The unique identifier of the document |
Response (200 OK)
{
"success": true,
"data": {
"id": "9c8e7f6d-5a4b-3c2d-1e0f-123456789abc",
"name": "Contract 2024.pdf",
"type": "pdf",
"file_path": "documents/abc123.pdf",
"content": "Full extracted text content from the document...",
"batch_id": "9c8e7f6d-5a4b-3c2d-1e0f-987654321xyz",
"batch": {
"id": "9c8e7f6d-5a4b-3c2d-1e0f-987654321xyz",
"name": "Upload Batch 1",
"status": "completed",
"total_documents": 10,
"processed_documents": 10,
"progress": 100
},
"processing_order": 1,
"vector_ids": [
"vec_9c8e7f6d5a4b3c2d1e0f123456789001",
"vec_9c8e7f6d5a4b3c2d1e0f123456789002",
"vec_9c8e7f6d5a4b3c2d1e0f123456789003"
],
"vector_ids_count": 25,
"metadata": {
"size": 2048576,
"mime_type": "application/pdf",
"processing_status": "completed",
"chunks_count": 25,
"processing_started": "2025-10-09 10:30:00",
"processing_completed": "2025-10-09 10:35:00",
"original_name": "Contract 2024.pdf"
},
"created_at": "2025-10-09 10:30:00",
"updated_at": "2025-10-09 10:35:00",
"deleted_at": null
}
}
Error Response (404 Not Found)
{
"success": false,
"message": "Document not found or access denied",
"error": "No query results for model [App\\Models\\Document]."
}
Documents Statistics
GETGet comprehensive statistics about your documents including totals, distribution by type and status, and recent activity.
Endpoint
https://ai.goodbits.tech/api/documents/statistics/overview
Response (200 OK)
{
"success": true,
"data": {
"total_documents": 150,
"total_chunks": 3750,
"documents_by_type": {
"pdf": 80,
"txt": 30,
"docx": 25,
"csv": 10,
"xlsx": 5
},
"documents_by_status": {
"completed": 140,
"processing": 5,
"failed": 3,
"queued": 2
},
"total_batches": 15,
"recent_uploads": 8
}
}
Statistics Fields
| Field | Type | Description |
|---|---|---|
| total_documents | Integer | Total number of documents in your account |
| total_chunks | Integer | Total number of vector chunks across all documents |
| documents_by_type | Object | Document count grouped by file type |
| documents_by_status | Object | Document count grouped by processing status |
| total_batches | Integer | Total number of upload batches |
| recent_uploads | Integer | Number of documents uploaded in the last 7 days |
List Batches
GETRetrieve a paginated list of all document batches with their processing status and progress information.
Endpoint
https://ai.goodbits.tech/api/documents/batches/list
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| per_page | Integer | No | Number of items per page (default: 15, max: 100) |
Response (200 OK)
{
"success": true,
"data": [
{
"id": "9c8e7f6d-5a4b-3c2d-1e0f-987654321xyz",
"name": "Upload Batch 1",
"status": "completed",
"total_documents": 10,
"processed_documents": 10,
"failed_documents": 0,
"progress_percentage": 100,
"documents_count": 10,
"metadata": {
"uploaded_by": "user@email.com",
"source": "web_interface",
"description": "Monthly reports upload"
},
"created_at": "2025-10-09 10:00:00",
"updated_at": "2025-10-09 10:45:00"
},
{
"id": "9c8e7f6d-5a4b-3c2d-1e0f-987654321abc",
"name": "API Upload - 2025-10-08",
"status": "processing",
"total_documents": 25,
"processed_documents": 18,
"failed_documents": 1,
"progress_percentage": 72,
"documents_count": 25,
"metadata": {
"uploaded_by": "api_user",
"source": "api",
"description": "Automated daily sync"
},
"created_at": "2025-10-08 15:30:00",
"updated_at": "2025-10-08 16:15:00"
}
],
"pagination": {
"total": 15,
"per_page": 15,
"current_page": 1,
"last_page": 1
}
}
Batch Status Values
| Status | Description |
|---|---|
| pending | Batch created but processing has not started |
| processing | Batch is currently being processed |
| completed | All documents in batch have been processed successfully |
| failed | Batch processing failed |
| partial | Some documents processed successfully, some failed |
List Batch Documents
GETRetrieve all documents that belong to a specific batch, ordered by their processing sequence.
Endpoint
https://ai.goodbits.tech/api/documents/batches/{batch_id}/documents
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| batch_id | UUID | Yes | The unique identifier of the batch |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| per_page | Integer | No | Number of items per page (default: 15, max: 100) |
Response (200 OK)
{
"success": true,
"batch": {
"id": "9c8e7f6d-5a4b-3c2d-1e0f-987654321xyz",
"name": "Upload Batch 1",
"status": "completed",
"progress_percentage": 100
},
"documents": [
{
"id": "9c8e7f6d-5a4b-3c2d-1e0f-123456789abc",
"name": "Contract 2024.pdf",
"type": "pdf",
"processing_order": 1,
"processing_status": "completed",
"chunks_count": 25,
"vector_ids_count": 25,
"created_at": "2025-10-09 10:30:00"
},
{
"id": "9c8e7f6d-5a4b-3c2d-1e0f-123456789def",
"name": "Invoice Q3.pdf",
"type": "pdf",
"processing_order": 2,
"processing_status": "completed",
"chunks_count": 18,
"vector_ids_count": 18,
"created_at": "2025-10-09 10:32:00"
},
{
"id": "9c8e7f6d-5a4b-3c2d-1e0f-123456789ghi",
"name": "Meeting Notes.txt",
"type": "txt",
"processing_order": 3,
"processing_status": "completed",
"chunks_count": 8,
"vector_ids_count": 8,
"created_at": "2025-10-09 10:33:00"
}
],
"pagination": {
"total": 10,
"per_page": 15,
"current_page": 1,
"last_page": 1
}
}
Error Response (404 Not Found)
{
"success": false,
"message": "Batch not found or access denied",
"error": "No query results for model [App\\Models\\DocumentBatch]."
}
Queries
The heart of DataBrain's RAG system is the ability to query your documents using natural language and receive accurate, context-aware responses.
Query RAG
POSTPerform a RAG query against all documents in your knowledge base.
Endpoint
https://ai.goodbits.tech/api/rag/query
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | String | Yes | The natural language query to process |
Example Request
{
"query": "What are the main points of the privacy policy document?"
}
Response (200 OK)
{
"answer": "The main points of the privacy policy include: 1) Collection of personal data only with consent; 2) Use of data to improve services; 3) No sharing of data with third parties without authorization; 4) User's right to access and rectify data; 5) Secure storage with encryption.",
"sources": [
{
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"document_name": "Privacy Policy.pdf",
"relevance": 0.92,
"content": "The privacy policy establishes that we collect personal data only with explicit user consent. We use this data exclusively to improve our services and user experience."
},
{
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"document_name": "Privacy Policy.pdf",
"relevance": 0.87,
"content": "We are committed not to share personal data with third parties without express authorization. All users have the right to access, rectify and delete their data at any time."
},
{
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"document_name": "Privacy Policy.pdf",
"relevance": 0.81,
"content": "All data is stored on secure servers with end-to-end encryption, ensuring maximum protection against leaks and unauthorized access."
}
]
}
Filtered Query
POSTPerform a RAG query against specific documents in your knowledge base.
Endpoint
https://ai.goodbits.tech/api/rag/filtered-query
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | String | Yes | The natural language query to process |
| document_ids | Array | Yes | Array of document IDs to query against |
Example Request
{
"query": "What are the main points of the privacy policy document?",
"document_ids": ["123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001"]
}
Response (200 OK)
{
"answer": "The main points of the privacy policy include: 1) Collection of personal data only with consent; 2) Use of data to improve services; 3) No sharing of data with third parties without authorization; 4) User's right to access and rectify data; 5) Secure storage with encryption.",
"sources": [
{
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"document_name": "Privacy Policy.pdf",
"relevance": 0.92,
"content": "The privacy policy establishes that we collect personal data only with explicit user consent. We use this data exclusively to improve our services and user experience."
},
{
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"document_name": "Privacy Policy.pdf",
"relevance": 0.87,
"content": "We are committed not to share personal data with third parties without express authorization. All users have the right to access, rectify and delete their data at any time."
},
{
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"document_name": "Privacy Policy.pdf",
"relevance": 0.81,
"content": "All data is stored on secure servers with end-to-end encryption, ensuring maximum protection against leaks and unauthorized access."
}
]
}
Training
Train your RAG model with custom data to improve response accuracy and domain-specific knowledge.
Train Model
POSTInitiate a training session with your documents to enhance the RAG model's understanding of your specific domain.
Endpoint
https://ai.goodbits.tech/api/training
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| document_ids | Array | Yes | Array of document IDs to use for training |
| training_mode | String | No | Training mode: "standard" or "intensive" (default: "standard") |
| epochs | Integer | No | Number of training epochs (default: 3, max: 10) |
Example Request
{
"document_ids": ["123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001"],
"training_mode": "intensive",
"epochs": 5
}
Response (202 Accepted)
{
"message": "Training session initiated successfully",
"training_id": "train_789e4567-e89b-12d3-a456-426614174000",
"status": "processing",
"estimated_completion_time": "2023-06-15T16:45:30Z",
"documents_count": 2,
"mode": "intensive",
"epochs": 5
}
Training Status
You can check the training status with a GET request:
GET https://ai.goodbits.tech/api/training/{training_id}/status
Status Response (200 OK)
{
"training_id": "train_789e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"progress": 100,
"started_at": "2023-06-15T14:30:00Z",
"completed_at": "2023-06-15T16:40:25Z",
"accuracy_improvement": 15.3,
"credits_used": 50
}
Credits
Monitor your API usage and available credits. Each API operation consumes credits based on complexity and resource usage.
Check Credits
GETRetrieve your current credit balance and usage statistics.
Endpoint
https://ai.goodbits.tech/api/credits
Parameters
No parameters required.
Response (200 OK)
{
"user_id": "user_123e4567-e89b-12d3-a456-426614174000",
"credits": {
"available": 8750,
"total": 10000,
"used": 1250
},
"usage_statistics": {
"current_month": {
"queries": 450,
"documents_uploaded": 23,
"training_sessions": 2,
"credits_used": 625
},
"last_month": {
"queries": 380,
"documents_uploaded": 19,
"training_sessions": 1,
"credits_used": 475
}
},
"subscription": {
"plan": "Professional",
"renewal_date": "2023-07-15T00:00:00Z",
"monthly_credit_allowance": 10000
},
"credit_pricing": {
"query": 1,
"document_upload": 5,
"training_standard": 25,
"training_intensive": 50
}
}
Credit Usage
| Operation | Credits Cost | Notes |
|---|---|---|
| RAG Query | 1 credit | Per query request |
| Document Upload | 5 credits | Per document, regardless of size |
| Training (Standard) | 25 credits | Per training session |
| Training (Intensive) | 50 credits | Per training session |
Code Examples
Here are some examples of how to use the DataBrain API in different programming languages.
Upload a Document
curl -X POST \
https://ai.goodbits.tech/api/rag/documents/upload \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Accept: application/json' \
-F 'document=@/path/to/your/document.pdf'
Query RAG
curl -X POST \
https://ai.goodbits.tech/api/rag/query \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"query": "What are the main points of the privacy policy?"
}'
Train Model
curl -X POST \
https://ai.goodbits.tech/api/training \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"document_ids": ["123e4567-e89b-12d3-a456-426614174000"],
"training_mode": "standard",
"epochs": 3
}'
Check Credits
curl -X GET \
https://ai.goodbits.tech/api/credits \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Accept: application/json'
Upload a Document
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://ai.goodbits.tech/api/rag/documents/upload",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => [
'document' => new CURLFILE('/path/to/your/document.pdf')
],
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_TOKEN",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Query RAG
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://ai.goodbits.tech/api/rag/query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'What are the main points of the privacy policy?'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Train Model
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://ai.goodbits.tech/api/training",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'document_ids' => ['123e4567-e89b-12d3-a456-426614174000'],
'training_mode' => 'standard',
'epochs' => 3
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_TOKEN",
"Content-Type: application/json",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Check Credits
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://ai.goodbits.tech/api/credits",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_TOKEN",
"Accept: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Upload a Document
import requests
url = "https://ai.goodbits.tech/api/rag/documents/upload"
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Accept': 'application/json'
}
files = {
'document': open('/path/to/your/document.pdf', 'rb')
}
response = requests.post(url, headers=headers, files=files)
print(response.json())
Query RAG
import requests
import json
url = "https://ai.goodbits.tech/api/rag/query"
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
payload = {
'query': 'What are the main points of the privacy policy?'
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())
Train Model
import requests
import json
url = "https://ai.goodbits.tech/api/training"
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
payload = {
'document_ids': ['123e4567-e89b-12d3-a456-426614174000'],
'training_mode': 'standard',
'epochs': 3
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())
Check Credits
import requests
url = "https://ai.goodbits.tech/api/credits"
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.json())
Upload a Document
const fs = require('fs');
const axios = require('axios');
const FormData = require('form-data');
async function uploadDocument() {
const formData = new FormData();
formData.append('document', fs.createReadStream('/path/to/your/document.pdf'));
try {
const response = await axios.post('https://ai.goodbits.tech/api/rag/documents/upload', formData, {
headers: {
...formData.getHeaders(),
'Authorization': 'Bearer YOUR_API_TOKEN',
'Accept': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
}
uploadDocument();
Query RAG
const axios = require('axios');
async function queryRag() {
try {
const response = await axios.post('https://ai.goodbits.tech/api/rag/query', {
query: 'What are the main points of the privacy policy?'
}, {
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
}
queryRag();
Train Model
const axios = require('axios');
async function trainModel() {
try {
const response = await axios.post('https://ai.goodbits.tech/api/training', {
document_ids: ['123e4567-e89b-12d3-a456-426614174000'],
training_mode: 'standard',
epochs: 3
}, {
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
}
trainModel();
Check Credits
const axios = require('axios');
async function checkCredits() {
try {
const response = await axios.get('https://ai.goodbits.tech/api/credits', {
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Accept': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
}
checkCredits();
Need Help With Integration?
Our team of experts is ready to assist you with implementing DataBrain's RAG API into your applications. Contact us for personalized support.
Contact Support TeamComprehensive Documentation
Explore our in-depth guides and tutorials to master DataBrain's RAG capabilities.
Browse GuidesClient Libraries
Use our official SDKs for popular programming languages to accelerate integration.
View SDKsDeveloper Community
Join our community forum to share insights and get help from fellow developers.
Join Community