Skip to content

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://access.demo.satori-labs.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., https://api.satorivault.com)
  • HTTP Client: curl, Postman, or any HTTP client library for your programming language
  • API Token: Your JWT token for authentication (provided by your Satori administrator)
  • Tenant ID: Your tenant ID (provided by your Satori administrator)

If you don't have these credentials, contact your Satori administrator 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 "https://api.satorivault.com/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 https://api.satorivault.com 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 "https://api.satorivault.com/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",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response:

{
  "id": "750e8400-e29b-41d4-a716-446655440000",
  "name": "My First Enclave",
  "description": "Workspace for document processing",
  "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 "https://api.satorivault.com/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 "https://api.satorivault.com/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 "https://api.satorivault.com/api/tenants/550e8400-e29b-41d4-a716-446655440000/enclaves/750e8400-e29b-41d4-a716-446655440000/query?query=What%20are%20the%20key%20points%20in%20this%20document?" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>"

Response:

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

Complete Example Script

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

import requests
import time
import uuid

# Configuration
BASE_URL = "https://api.satorivault.com"  # 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}"},
    params={"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., https://api.satorivault.com/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:

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