Sphere RAG API

Getting Started

The Sphere RAG API provides endpoints for embedding generation and retrieval-augmented generation operations. This documentation will help you understand how to use each endpoint effectively.

The base URL for all API requests is: https://api.getsphere.ai

Our API consists of 5 main endpoints:

• /chunks: Retrieve relevant content chunks based on a query
• /generate: Generate answers based on retrieved chunks
• /embeddings: Generate vector embeddings for text content
• /batch_embeddings: Generate embeddings for multiple texts in batch
• /health: Health check endpoint

For interactive API documentation with a testing interface, visit our Swagger UI docs.

Authentication

All API requests require authentication using an API key. You can obtain your API key by contacting our team.

To authenticate your requests, include your API key in the X-API-Key header:

X-API-Key: your_api_key_here

API Endpoints

{
  "query": "What are the key factors in climate change?",
  "top_k": 5,
  "matching_threshold": 0.75
}

{
  "chunks": [
    {
      "chunk_id": "789012",
      "price": 0.01,
      "publisher": {"id": "pub-456", "name": "Environmental Science Institute"},
      "publication": {
        "id": "journal-789",
        "title": "Climate Research Journal",
        "issn": "5678-9012"
      },
      "media_type": "text/plain",
      "content": "Carbon dioxide emissions are a primary driver of global climate change...",
      "distance": 0.12,
      "timestamp": "2023-02-18T10:15:00Z",
      "created_at": "2023-02-19T08:30:45Z",
      "related_chunks": []
    }
  ],
  "timing": {
    "embedding_seconds": 0.25,
    "postgres_search_seconds": 0.15,
    "retrieval_seconds": 0.40,
    "total_seconds": 0.40
  }
}

{
  "query": "What are the benefits of exercise on mental health?",
  "top_k": 5,
  "matching_threshold": 0.75
}

{
  "answer": "Regular exercise has been shown to have significant positive effects on mental health...",
  "chunks": [
    {
      "chunk_id": "123456",
      "price": 0.01,
      "publisher": {"id": "pub-123", "name": "Health Research Institute"},
      "publication": {
        "id": "journal-456",
        "title": "Journal of Mental Health",
        "issn": "1234-5678"
      },
      "media_type": "text/plain",
      "content": "Studies have shown that regular exercise can reduce symptoms of depression and anxiety...",
      "distance": 0.15,
      "timestamp": "2023-01-15T14:30:00Z",
      "created_at": "2023-01-16T09:45:22Z",
      "related_chunks": []
    }
  ],
  "timing": {
    "embedding_seconds": 0.25,
    "postgres_search_seconds": 0.15,
    "retrieval_seconds": 0.40,
    "generation_seconds": 1.20,
    "total_seconds": 1.60
  }
}

{
  "content": "This is a sample text for embedding generation"
}

{
  "embedding": [0.023, -0.045, 0.011, 0.087, -0.193, ...],
  "dimension": 1024
}

{
  "contents": [
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
  ]
}

{
  "embeddings": [
    [0.023, -0.045, 0.011, ...],
    [0.031, -0.052, 0.018, ...],
    [0.019, -0.038, 0.009, ...]
  ],
  "processing_time_ms": 150.25,
  "avg_per_item_ms": 50.08
}

{
  "status": "healthy",
  "service": "sphere_rag"
}

Code Examples

Python

import requests
import json

API_URL = "https://api.getsphere.ai"
API_KEY = "your_api_key_here"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY
}

# Health check
def health_check():
    response = requests.get(f"{API_URL}/health")
    return response.json()

# Generate single embedding
def get_embedding(text):
    response = requests.post(
        f"{API_URL}/embeddings",
        headers=HEADERS,
        json={"content": text}
    )
    return response.json()

# Generate batch embeddings
def get_batch_embeddings(texts):
    response = requests.post(
        f"{API_URL}/batch_embeddings",
        headers=HEADERS,
        json={"contents": texts}
    )
    return response.json()

# Get relevant chunks
def get_chunks(query, top_k=5):
    response = requests.post(
        f"{API_URL}/chunks",
        headers=HEADERS,
        json={"query": query, "top_k": top_k}
    )
    return response.json()

# Generate answer from content
def get_answer(query, top_k=5):
    response = requests.post(
        f"{API_URL}/generate",
        headers=HEADERS,
        json={"query": query, "top_k": top_k}
    )
    return response.json()

# Example usage
health = health_check()
embedding = get_embedding("What is machine learning?")
batch_embeddings = get_batch_embeddings(["Text 1", "Text 2", "Text 3"])
chunks = get_chunks("How does climate change affect biodiversity?")
answer = get_answer("What are the benefits of exercise?")

JavaScript

const API_URL = 'https://api.getsphere.ai';
const API_KEY = 'your_api_key_here';
const HEADERS = {
  'Content-Type': 'application/json',
  'X-API-Key': API_KEY
};

// Health check
async function healthCheck() {
  const response = await fetch(`${API_URL}/health`);
  return response.json();
}

// Generate single embedding
async function getEmbedding(text) {
  const response = await fetch(`${API_URL}/embeddings`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({ content: text })
  });
  return response.json();
}

// Generate batch embeddings
async function getBatchEmbeddings(texts) {
  const response = await fetch(`${API_URL}/batch_embeddings`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({ contents: texts })
  });
  return response.json();
}

// Get relevant chunks
async function getChunks(query, topK = 5) {
  const response = await fetch(`${API_URL}/chunks`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({ query, top_k: topK })
  });
  return response.json();
}

// Generate answer from content
async function getAnswer(query, topK = 5) {
  const response = await fetch(`${API_URL}/generate`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({ query, top_k: topK })
  });
  return response.json();
}

// Example usage
healthCheck().then(health => console.log(health));
getEmbedding("What is machine learning?").then(embedding => console.log(embedding));
getBatchEmbeddings(["Text 1", "Text 2", "Text 3"]).then(embeddings => console.log(embeddings));
getChunks("How does climate change affect biodiversity?").then(chunks => console.log(chunks));
getAnswer("What are the benefits of exercise?").then(answer => console.log(answer));