Complete API Reference

Production-ready REST API with streaming support, multi-tenant isolation, and AI-powered features. Integrate in any language.

Quick Start Guide

1. Register & Get API Key

Free registration in seconds

curl -X POST http://localhost:3000/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "organizationName": "Your Company"
  }'

Response:

{
  "success": true,
  "data": {
    "apiKey": "sk_live_abc123...",
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "scopes": ["tenant:read", "chat:create", "file:upload", ...]
  }
}

Chat API (Streaming)

The Chat API provides AI-powered conversational capabilities with real-time streaming responses, RAG (Retrieval-Augmented Generation) support, and function calling. Perfect for customer support, sales assistance, and interactive chatbots.

POST /api/v1/chat

Send chat message with streaming SSE response

Description

Initiates a chat conversation with the AI. Responses are streamed in real-time using Server-Sent Events (SSE), allowing for immediate feedback and progressive rendering of text. The API automatically retrieves relevant documents from your RAG store and can execute function calls for dynamic actions.

Request Body

Parameter	Type	Required	Description
`tenantId`	string	Yes	Your tenant identifier from registration
`message`	string	Yes	User's chat message (max 10,000 characters)
`accountId`	string	Optional	Account ID for multi-user tracking
`conversationId`	string	Optional	Conversation ID for continuing existing chats

Streaming Event Types

text-deltaStreaming text chunks as AI generates response
tool-input-startTool call initiated with input parameters
tool-output-availableTool execution completed with results
data-citationsSource documents from RAG with file names and IDs
finishStream complete, connection can be closed

Rate Limits & Constraints

• 100 requests per minute per tenant
• 1,000 requests per hour per tenant
• Max message length: 10,000 characters
• Max concurrent connections: 10 per tenant
• Stream timeout: 60 seconds

Best Practices

✓ Always handle SSE connection properly (reconnect on errors)
✓ Parse and display citations to users for transparency
✓ Use conversationId to maintain context across messages
✓ Implement progressive rendering for better UX
✓ Handle tool calls gracefully in your UI

Code Examples

curl -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "YOUR_TENANT_ID",
    "message": "What is the price for 2 cbm storage?",
    "accountId": "customer-123"
  }' \
  http://localhost:3000/api/v1/chat

# Example streaming response:
# data: {"type":"text-delta","delta":"The "}
# data: {"type":"text-delta","delta":"price "}
# data: {"type":"data-citations","citations":[{"fileName":"pricing.pdf"}]}
# data: {"type":"finish"}

Estimator API (Streaming)

The Estimator API analyzes images to detect items, calculate dimensions and volumes, and provide packing recommendations for moving and storage. Uses advanced computer vision and 3D bin packing algorithms for accurate size estimation.

POST /api/v1/estimator/analyze

Analyze images with streaming results and recommendations

Description

Upload one or more images of items (furniture, boxes, equipment) to receive AI-powered analysis including item detection, size estimation, volume calculation, and optimal packing recommendations. Results stream in real-time for immediate feedback.

Request Body

Parameter	Type	Required	Description
`tenantId`	string	Yes	Your tenant identifier
`images`	string[]	Yes	Array of public image URLs (max 10 images, 10MB each)
`accountId`	string	Optional	Account ID for tracking

Streaming Events

text-deltaAI explanation of detected items and reasoning
data-manageItemsDetected items with dimensions (L×W×H), weight, and volume
data-status-updateProcessing status (analyzing, calculating, optimizing)
data-recommendationFinal recommendation with box sizes, 3D visualization data, and cost estimate

Rate Limits & Constraints

• 20 requests per minute per tenant
• 200 requests per hour per tenant
• Max images per request: 10
• Max image size: 10MB each
• Supported formats: JPEG, PNG, WebP
• Processing timeout: 120 seconds

Best Practices

✓ Use clear, well-lit photos from multiple angles
✓ Include reference objects (e.g., phone, ruler) for scale
✓ Avoid blurry or dark images for better accuracy
✓ Process status updates to show progress to users
✓ Compress images to reduce upload time
✓ Use 3D visualization data for interactive displays

Common Use Cases

• Moving & relocation: Calculate truck size needed
• Storage facilities: Recommend unit sizes
• E-commerce: Estimate shipping box requirements
• Inventory management: Track space utilization

Code Examples

curl -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "YOUR_TENANT_ID",
    "images": [
      "https://example.com/chair.jpg",
      "https://example.com/table.jpg"
    ]
  }' \
  http://localhost:3000/api/v1/estimator/analyze

# Example response stream:
# data: {"type":"text-delta","delta":"I can see "}
# data: {"type":"data-status-update","status":"Analyzing images..."}
# data: {"type":"data-manageItems","items":[{"name":"Chair","dimensions":{"length":50,"width":50,"height":90},"volume":0.225}]}
# data: {"type":"data-recommendation","recommendationDetails":{"recommendedBox":"Medium","totalVolume":0.5}}

Files & RAG Store API

Manage your RAG (Retrieval-Augmented Generation) document store for AI-powered search and citation. Upload documents, sync from AssetVault, configure file settings, and perform bulk operations.

GET /api/v1/tenants/{tenantId}/store

Get RAG store details and statistics

Retrieve comprehensive information about your RAG store including file count, storage usage, sync status, and file metadata.

Response Includes

• Total files, active files, excluded files count
• Storage usage and quotas
• Last sync timestamp
• File list with metadata (name, size, status, citations enabled)

curl -H "x-api-key: YOUR_API_KEY" \
  http://localhost:3000/api/v1/tenants/YOUR_TENANT_ID/store

POST /api/v1/tenants/{tenantId}/store/sync

Sync files from AssetVault to RAG store

Import documents from your AssetVault storage into the RAG store for AI-powered search. Sync all files or specific files by providing file IDs.

Sync Behavior

• Without fileIds: Syncs all files from AssetVault
• With fileIds: Syncs only specified files
• Files are queued for processing (async)
• Processing time: ~30s per file
• Supports PDF, TXT, DOC, DOCX formats

# Sync all files
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  http://localhost:3000/api/v1/tenants/YOUR_TENANT_ID/store/sync

# Sync specific files
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileIds": ["asset-id-1", "asset-id-2"]}' \
  http://localhost:3000/api/v1/tenants/YOUR_TENANT_ID/store/sync

POST /api/v1/tenants/{tenantId}/store/refresh

Refresh document metadata from Google File Search

Update file metadata (names, sizes, modification dates) from Google's File Search storage. Useful after renaming files or updating documents.

Important Notes

• Only updates metadata, not file content
• Does not re-import or re-process files
• Use after renaming files in AssetVault
• Rate limit: 10 requests per hour

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  http://localhost:3000/api/v1/tenants/YOUR_TENANT_ID/store/refresh

POST /api/v1/tenants/{tenantId}/store/files/actions

Bulk file operations (toggle, exclude, delete)

Perform bulk operations on multiple files simultaneously. Configure citation settings, exclude files from search, or permanently delete documents.

Available Actions

toggle_citation

Enable/disable citation display for specific files

toggle_manual_send

Enable/disable manual send requirement

exclude

Remove files from RAG queries (keeps file)

include

Re-enable files in RAG queries

delete

Permanently delete files (irreversible)

reimport

Re-import and re-process from Google

# Toggle citation
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "toggle_citation",
    "fileIds": ["files/abc123"],
    "enabled": true
  }' \
  http://localhost:3000/api/v1/tenants/YOUR_TENANT_ID/store/files/actions

# Exclude files from search
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "exclude",
    "fileIds": ["files/abc123", "files/def456"]
  }' \
  http://localhost:3000/api/v1/tenants/YOUR_TENANT_ID/store/files/actions

Tenants & Accounts API

Multi-tenant architecture APIs for managing organizations (tenants) and user accounts. Create isolated environments, manage permissions, and organize file storage per account.

POST /api/v1/tenants

Create a new tenant (admin only)

Create a new tenant organization with isolated data storage, RAG store, and configuration. Each tenant gets a unique ID and can have multiple accounts.

Admin Only

This endpoint requires admin-level API key. Regular tenants cannot create other tenants.

curl -X POST \
  -H "x-api-key: ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "config": {
      "tier": "premium",
      "features": ["chat", "files", "estimator"]
    }
  }' \
  http://localhost:3000/api/v1/tenants

GET /api/v1/tenants/{tenantId}

Get tenant details and configuration

Retrieve detailed information about a tenant including name, configuration, subscription tier, and feature flags.

curl -H "x-api-key: YOUR_API_KEY" \
  http://localhost:3000/api/v1/tenants/YOUR_TENANT_ID

POST /api/v1/tenants/{tenantId}/accounts

Create user account within tenant

Create a new user account under a tenant. Each account has isolated file storage and can have custom metadata for tracking.

Use Cases

• Multi-user SaaS applications
• Customer account management
• Separate file storage per user
• Usage tracking and analytics

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "metadata": {
      "role": "admin",
      "department": "Sales"
    }
  }' \
  http://localhost:3000/api/v1/tenants/YOUR_TENANT_ID/accounts

GET /api/v1/tenants/{tenantId}/accounts/{accountId}

Get account details

Retrieve account information including email, permissions, metadata, and file storage statistics.

curl -H "x-api-key: YOUR_API_KEY" \
  http://localhost:3000/api/v1/tenants/TENANT_ID/accounts/ACCOUNT_ID

PATCH /api/v1/tenants/{tenantId}/accounts/{accountId}

Update account permissions or metadata

Modify account permissions, update metadata, or change configuration. Only provided fields are updated.

Partial Updates

PATCH supports partial updates - only send fields you want to change. Existing values are preserved.

curl -X PATCH \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["read", "write", "delete"],
    "metadata": {"department": "Engineering"}
  }' \
  http://localhost:3000/api/v1/tenants/TENANT_ID/accounts/ACCOUNT_ID

POST /api/v1/tenants/{tenantId}/accounts/{accountId}/files

Upload file to account's RAG store

Upload documents to an account's isolated file storage. Files are automatically processed and added to the RAG store for AI-powered search.

Supported Formats

• PDF (.pdf) - Up to 100 pages
• Text (.txt) - UTF-8 encoding
• Word (.doc, .docx) - Max 10MB
• Files must be publicly accessible via URL
• Processing time: ~30 seconds per file

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://cdn.example.com/contract.pdf",
    "fileName": "contract.pdf",
    "mimeType": "application/pdf",
    "metadata": {"category": "legal", "year": "2024"}
  }' \
  http://localhost:3000/api/v1/tenants/TENANT_ID/accounts/ACCOUNT_ID/files

GET /api/v1/tenants/{tenantId}/accounts/{accountId}/files

List all files for account

Retrieve a list of all files uploaded to an account's storage, including metadata, processing status, and file statistics.

curl -H "x-api-key: YOUR_API_KEY" \
  http://localhost:3000/api/v1/tenants/TENANT_ID/accounts/ACCOUNT_ID/files

DELETE /api/v1/tenants/{tenantId}/accounts/{accountId}/files/{fileId}

Permanently delete file

Permanently remove a file from the account's storage and RAG store. This action is irreversible.

Irreversible Action

File deletion is permanent and cannot be undone. The file will be removed from both storage and the RAG search index.

curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY" \
  http://localhost:3000/api/v1/tenants/TENANT_ID/accounts/ACCOUNT_ID/files/FILE_ID

Authentication

API Key Authentication

All API requests (except registration) require authentication via the x-api-key header.

Security Best Practices

✓ Store API keys in environment variables
✓ Never commit keys to version control
✓ Use different keys for dev/staging/production
✓ Rotate keys regularly
✓ Monitor API usage for anomalies

Error Handling

HTTP Status Codes

200

Success

Request completed successfully

201

Created

Resource created successfully

400

Bad Request

Invalid request body or parameters

401

Unauthorized

Missing or invalid API key

403

Forbidden

Insufficient permissions

404

Not Found

Resource does not exist

429

Rate Limit Exceeded

Too many requests

500

Internal Server Error

Server error - contact support

Error Response Format

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API Key"
  }
}

Complete API Endpoints

POST

/api/v1/register

Public

POST

/api/v1/tenants

Create new tenant

admin

GET

/api/v1/tenants/{tenantId}

Get tenant details

tenant:read

POST

/api/v1/chat

Send chat message (streaming SSE)

chat:create

POST

/api/v1/estimator/analyze

Analyze images (streaming)

estimator:use

GET

/api/v1/tenants/{tenantId}/store

Get RAG store details

file:read

POST

/api/v1/tenants/{tenantId}/store/sync

Sync files from AssetVault

file:upload

POST

/api/v1/tenants/{tenantId}/store/refresh

Refresh document metadata

file:write

POST

/api/v1/tenants/{tenantId}/store/files/actions

Bulk file operations

file:write

POST

/api/v1/tenants/{tenantId}/accounts

Create account

account:write

GET

/api/v1/tenants/{tenantId}/accounts/{accountId}

Get account details

account:read

PATCH

/api/v1/tenants/{tenantId}/accounts/{accountId}

Update account

account:write

POST

/api/v1/tenants/{tenantId}/accounts/{accountId}/files

Upload file to RAG store

file:upload

GET

/api/v1/tenants/{tenantId}/accounts/{accountId}/files

List files

file:read

DELETE

/api/v1/tenants/{tenantId}/accounts/{accountId}/files/{fileId}

Delete file

file:delete

Ready to Get Started?

Get your API key and start building in minutes