Skip to content

api_documentation.md

Latest commit

 

History

History
184 lines (143 loc) · 4.63 KB

api_documentation.md

File metadata and controls

184 lines (143 loc) · 4.63 KB

RAGForge API Documentation

Welcome to the RAGForge API documentation. This guide provides instructions on how to programmatically interact with the RAGForge platform to manage projects, pipelines, and perform RAG (Retrieval-Augmented Generation) queries.

Table of Contents

  1. Base URL
  2. Authentication
  3. tRPC Protocol
  4. Endpoints
  5. Code Examples

Base URL

All API requests should be made to: http://localhost:3000/api/trpc (Local Development) https://your-domain.com/api/trpc (Production)

Authentication

RAGForge supports two methods of authentication:

1. Web-based Authentication (Clerk)

For browser-based interactions, RAGForge uses Clerk for identity management. Session cookies (app_session_id) are automatically managed when using the web dashboard.

2. Programmatic Access (API Keys)

For server-to-server or script-based access, you can generate API keys in the Settings > API Keys section of the dashboard.

How to use API Keys: Include your API key in the X-API-Key header of every request.

curl -H "X-API-Key: rg_your_api_key_here" ...

tRPC Protocol

RAGForge uses the tRPC protocol. All requests are GET (for queries) or POST (for mutations).

  • Payload Structure: Requests sent to /api/trpc/[router].[method] expect a JSON object in the input query parameter (for GET) or request body (for POST).
  • Batching: tRPC supports batching multiple calls into a single HTTP request.

Endpoints

Projects

Manage top-level organizational units.

  • projects.list (Query): List all projects owned by the user.
  • projects.create (Mutation): { name: string, description?: string }
  • projects.delete (Mutation): { projectId: number }

Pipelines

Manage RAG pipelines within a project.

  • pipelines.list (Query): { projectId: number }
  • pipelines.get (Query): { pipelineId: number }
  • pipelines.status (Query): { pipelineId: number } - Returns ingestion stats and usage.

Versions

Manage configuration versions for a pipeline.

  • versions.list (Query): { pipelineId: number }
  • versions.updateConfig (Mutation): 
    {
  "versionId": number,
  "chunkSize": number,
  "chunkOverlap": number,
  "enableGraphRAG": boolean
}

Documents

Upload and manage knowledge sources.

  • documents.list (Query): { versionId: number }
  • documents.getPresignedUrl (Mutation): { versionId: number, filename: string, fileType: string } - Returns an S3 pre-signed URL for upload.
  • documents.upload (Mutation): Register a completed upload.
  • documents.confirmOCR (Mutation): { documentId: number } - Manually trigger OCR for low-content PDFs.

Search

Perform raw semantic search across documents.

  • search.query (Query): 
    {
  "versionId": number,
  "query": string,
  "limit": number
}

Chat

Perform RAG-powered conversations.

  • chat.query (Mutation): 
    {
  "versionId": number,
  "message": string,
  "systemPrompt": string (optional)
}
    Response: 
    {
  "response": "The answer generated by LLM...",
  "sources": [
    { "documentName": "doc1.pdf", "pageNo": 5, "text": "..." }
  ],
  "tokensUsed": 1542
}

Code Examples

Python Integration

import requests
import json

BASE_URL = "http://localhost:3000/api/trpc"
API_KEY = "rg_your_actual_key"

def rag_query(version_id, message):
    url = f"{BASE_URL}/chat.query"
    headers = {
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    }
    payload = {
        "json": {
            "versionId": version_id,
            "message": message
        }
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    return response.json()

# Example Usage
result = rag_query(1, "What is the summary of the Urdu document?")
print(result['result']['data']['response'])

Node.js (tRPC Client)

import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from './server/routers';

const client = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000/api/trpc',
      headers() {
        return {
          'X-API-Key': 'rg_your_actual_key',
        };
      },
    }),
  ],
});

const response = await client.chat.query.mutate({
  versionId: 1,
  message: "Tell me about the Quranic evidence.",
});