Quick Reference

Base Configuration

import requests
from openai import OpenAI

# Base URL for API
BASE_URL = "https://vedaya-kge.fly.dev"

# Authentication - API works without it
headers = {"Content-Type": "application/json"}
# If you have an API key (optional):
# headers["Authorization"] = f"Bearer {API_KEY}"

# For OpenAI-compatible queries
client = OpenAI(
    api_key="sk-dummy",  # Works with any dummy key
    base_url=f"{BASE_URL}/v1"
)

Most Common Operations

Complete Working Workflow

import requests
import time
from openai import OpenAI

# 1. Upload text documents (recommended method)
documents = [
    "Your first document content here...",
    "Your second document content here..."
]

response = requests.post(
    f"{BASE_URL}/documents/texts",
    headers={"Content-Type": "application/json"},
    json={
        "texts": documents,
        "file_sources": [f"doc_{i}.txt" for i in range(len(documents))]
    }
)

# 2. Wait for processing (usually seconds, not minutes)
for i in range(30):
    status = requests.get(f"{BASE_URL}/documents/pipeline_status").json()
    if not status.get('busy', False):
        print("✅ Processing complete!")
        break
    time.sleep(2)

# 3. Query using OpenAI-compatible interface (primary method)
client = OpenAI(api_key="sk-dummy", base_url=f"{BASE_URL}/v1")

response = client.chat.completions.create(
    model="vedaya-hybrid",  # Special RAG model
    messages=[{"role": "user", "content": "Your question here"}],
    temperature=0.7,
    max_tokens=500
)

print(response.choices[0].message.content)

Available RAG Models

Use with OpenAI-compatible endpoint:
ModelPurposeExample
vedaya-naiveBasic keyword searchmodel="vedaya-naive"
vedaya-localEntity-focusedmodel="vedaya-local"
vedaya-globalRelationshipsmodel="vedaya-global"
vedaya-hybridCombined (default)model="vedaya-hybrid"

Quick Functions

Query with Fallback

def query_vedaya(question, mode="vedaya-hybrid"):
    """Query with automatic HTTP fallback"""
    try:
        from openai import OpenAI
        client = OpenAI(api_key="sk-dummy", base_url=f"{BASE_URL}/v1")
        response = client.chat.completions.create(
            model=mode,
            messages=[{"role": "user", "content": question}],
            temperature=0.7,
            max_tokens=500
        )
        return response.choices[0].message.content
    except:
        # Fallback to HTTP
        response = requests.post(
            f"{BASE_URL}/v1/chat/completions",
            json={
                "model": mode,
                "messages": [{"role": "user", "content": question}],
                "temperature": 0.7,
                "max_tokens": 500
            }
        )
        if response.status_code == 200:
            return response.json()['choices'][0]['message']['content']
        return f"Error: {response.status_code}"

Endpoint Reference

Document Management

  • POST /documents/texts - Upload text documents (recommended)
  • POST /documents/upload - Upload files to input directory
  • POST /documents/file - Direct file processing
  • POST /documents/file_batch - Batch file upload
  • GET /documents - List all documents
  • DELETE /documents - Clear all documents
  • GET /documents/pipeline_status - Check processing status
  • POST /documents/scan - Scan input directory
  • POST /documents/clear_cache - Clear cache

Query/RAG

  • POST /v1/chat/completions - OpenAI-compatible chat (primary)
  • POST /query - Native query endpoint (alternative)
  • POST /query/stream - Streaming (Note: returns 404 currently)

Knowledge Graph

  • GET /graph/label/list - List entities
  • GET /graphs - Get subgraph
  • GET /graph/entity/exists - Check if entity exists
  • POST /graph/entity/edit - Update entity
  • POST /graph/relation/edit - Update relation

Compatibility

  • POST /v1/chat/completions - OpenAI chat completions
  • POST /v1/embeddings - Generate embeddings
  • GET /v1/models - List available models

System

  • GET /health - Health check
  • POST /login - Authentication (optional - API works without it)

Important Notes

What Works
  • Authentication optional (dummy keys work)
  • Text upload via /documents/texts
  • OpenAI SDK with base_url="/v1"
  • Special vedaya-* models for RAG
  • Fast processing (seconds not minutes)
  • Multi-turn conversations
What Doesn’t Work
  • Streaming responses (returns 404)
  • OAuth2 flow (use dummy keys instead)
  • /openai/v1 endpoint (use /v1)