Quick Start Guide

Get up and running with Satori's API-powered information enclaves in minutes. This guide will walk you through creating your first information enclave, uploading documents, and using intelligent file chat.

Try the Demo First

Before setting up your own instance, you can explore Satori through our demo project:

https://web-demo.satorivault.com/

Note: The demo requires a Satori account. To get started, either:

• Self-onboard through the Satori Portal to create your account, or
• Contact your Tryal Accelerator site administrator to request direct Satori access

The demo environment allows you to:

• See basic usage of the system
• Add your own API keys to test your setup
• Experiment with file uploads and intelligent file chat

This is a great way to get familiar with Satori's capabilities before configuring your own deployment.

Prerequisites

Before you begin, you'll need:

• API Access: The URL of your Satori API instance (e.g., __API_HOST__)
• HTTP Client: curl, Postman, or any HTTP client library for your programming language
• API Token: Your JWT token for authentication (create via Satori Portal or provided by your administrator)
• Tenant ID: Your tenant ID (available in Satori Portal or provided by your administrator)

If you don't have these credentials, sign up for a Satori account to get started.

Step 1: Create an API Token (if needed)

If you need to create a new API token, you can do so using your existing token:

curl -X POST "__API_HOST__/api/tenants/{tenant_id}/tokens/" \
  -H "Authorization: Bearer <YOUR_EXISTING_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Token"
  }'

Note: Replace {tenant_id} with your tenant ID and __API_HOST__ with your actual API URL.

Response:

{
  "id": "650e8400-e29b-41d4-a716-446655440000",
  "name": "My API Token",
  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "is_active": true,
  "created_at": "2025-01-15T10:05:00Z"
}

Important: Save the key value - this is your JWT token. You won't be able to retrieve it again.

Step 2: Create an Information Enclave

An information enclave is a secure workspace for your documents. Create one for your project:

curl -X POST "__API_HOST__/api/tenants/550e8400-e29b-41d4-a716-446655440000/enclaves/" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Enclave",
    "description": "Workspace for document processing",
    "enclave_type": "clinical_study",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Enclave Types

Satori supports different enclave types that customize document classification and AI behavior:

Type	Value	Description
Clinical Study	clinical_study	Optimized for clinical trials, medical research, and regulatory documents. Uses 51 specialized document types.
Generic	generic	General-purpose for business documents, contracts, reports, and technical documentation. Uses 15 general document types.

Default: If enclave_type is not specified, it defaults to clinical_study.

For detailed guidance on choosing enclave types, see the Enclave Types Guide.

Response:

{
  "id": "750e8400-e29b-41d4-a716-446655440000",
  "name": "My First Enclave",
  "description": "Workspace for document processing",
  "enclave_type": "clinical_study",
  "is_active": true,
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-01-15T10:10:00Z",
  "updated_at": "2025-01-15T10:10:00Z"
}

Save the enclave id for file operations.

Step 3: Upload a File

Upload a document to your enclave. Satori supports PDFs, Word documents, images, videos, audio files, and more:

curl -X POST "__API_HOST__/api/tenants/550e8400-e29b-41d4-a716-446655440000/enclaves/750e8400-e29b-41d4-a716-446655440000/files/" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -F "file=@/path/to/your/document.pdf" \
  -F 'metadata={"author": "John Doe", "category": "research"}'

Response:

{
  "id": "850e8400-e29b-41d4-a716-446655440000",
  "name": "document.pdf",
  "content_type": "application/pdf",
  "size_bytes": 245000,
  "status": "pending",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "enclave_id": "750e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-01-15T10:15:00Z"
}

The file status will be pending initially. It will progress through:

• pending → processing → building_artifacts → ready

Step 4: Check File Status

Files are processed automatically after upload. Check the status to know when your file is ready:

curl -X GET "__API_HOST__/api/tenants/550e8400-e29b-41d4-a716-446655440000/enclaves/750e8400-e29b-41d4-a716-446655440000/files/850e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>"

The file status will progress from pending → processing → ready. Wait until the status is ready before querying. You can also set up webhooks to be notified when processing completes.

Step 5: Use Intelligent File Chat

Once your file is ready, you can use Satori's intelligent file chat to ask questions about it using natural language:

curl -X POST "__API_HOST__/api/tenants/550e8400-e29b-41d4-a716-446655440000/enclaves/750e8400-e29b-41d4-a716-446655440000/query" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the key points in this document?"}'

Response:

{
  "answer": "The key points in this document include...",
  "sources": [
    {
      "node_id": "node_abc123",
      "text": "Relevant document excerpt...",
      "score": 0.95
    }
  ]
}

Optional: Download Your File

You can download files in their original format. Files are streamed directly with the original filename:

curl -X GET "__API_HOST__/api/tenants/550e8400-e29b-41d4-a716-446655440000/enclaves/750e8400-e29b-41d4-a716-446655440000/files/850e8400-e29b-41d4-a716-446655440000/download" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -O -J

The file will download with its original filename via Content-Disposition header.

Complete Example Script

Here's a complete Python script that demonstrates the full workflow:

import requests
import time
import uuid

# Configuration
BASE_URL = "__API_HOST__"  # Replace with your API URL
TENANT_ID = "<YOUR_TENANT_ID>"  # Provided by your administrator
JWT_TOKEN = "<YOUR_JWT_TOKEN>"  # Provided by your administrator

# Step 1: Create enclave
enclave_response = requests.post(
    f"{BASE_URL}/api/tenants/{tenant_id}/enclaves/",
    headers={"Authorization": f"Bearer {JWT_TOKEN}", "Content-Type": "application/json"},
    json={"name": "Quick Start Enclave", "tenant_id": tenant_id}
)
enclave = enclave_response.json()
enclave_id = enclave["id"]
print(f"Created enclave: {enclave_id}")

# Step 2: Upload file
with open("document.pdf", "rb") as f:
    file_response = requests.post(
        f"{BASE_URL}/api/tenants/{tenant_id}/enclaves/{enclave_id}/files/",
        headers={"Authorization": f"Bearer {JWT_TOKEN}"},
        files={"file": f},
        data={"metadata": '{"source": "quick_start"}'}
    )
file = file_response.json()
file_id = file["id"]
print(f"Uploaded file: {file_id}, Status: {file['status']}")

# Step 3: Wait for processing
print("Waiting for file processing...")
while True:
    status_response = requests.get(
        f"{BASE_URL}/api/tenants/{tenant_id}/enclaves/{enclave_id}/files/{file_id}",
        headers={"Authorization": f"Bearer {JWT_TOKEN}"}
    )
    file_status = status_response.json()

    if file_status["status"] == "ready":
        print("File is ready!")
        break
    elif file_status["status"] == "failed":
        print("File processing failed!")
        exit(1)

    time.sleep(5)

# Step 4: Query the document
query_response = requests.post(
    f"{BASE_URL}/api/tenants/{tenant_id}/enclaves/{enclave_id}/query",
    headers={"Authorization": f"Bearer {JWT_TOKEN}", "Content-Type": "application/json"},
    json={"query": "What are the main topics in this document?"}
)
result = query_response.json()
print(f"\nQuery Answer:\n{result['answer']}")
print(f"\nSources: {len(result.get('sources', []))} document chunks found")

Using the Interactive API Docs

Satori provides interactive API documentation where you can test endpoints directly in your browser:

1. Navigate to your API's documentation URL (e.g., __API_HOST__/docs/api)
2. Click on any endpoint to see its details
3. Click "Try it out" to test the endpoint
4. Fill in the required parameters and authentication
5. Click "Execute" to make the request and see the response

The interactive docs include:

• Request/response examples
• Parameter descriptions
• Authentication requirements
• Error response formats

Next Steps

Now that you've completed the quick start:

• Best Practices Guide - Learn how to use Satori's API effectively
• File Management Guide - Deep dive into file operations
• Querying Documents Guide - Advanced intelligent file chat techniques
• API Reference - Explore all available endpoints (replace with your API URL)

Common Issues

File Processing Takes Too Long

• Large files (>100MB) can take 2-5 minutes
• Check file status periodically
• Use webhooks to get notified when processing completes

Authentication Errors

• Ensure you're using Bearer prefix: Authorization: Bearer <token>
• Verify token hasn't expired
• Check token belongs to the correct tenant

File Not Ready for Queries

• Wait until status is ready (not pending or processing)
• Check for failed status and review error details
• Verify file type is supported