Skip to main content

​
Base URL

  • Local: http://localhost:8787
  • Production: https://parti.metacogna.ai

​
Authentication

All authenticated endpoints require a session cookie: 
Cookie: pratejra_session=<token>
Session cookies are set on login and expire after 7 days.

​
Endpoints

​
Health & Debug

​
GET /

Service information and available endpoints.
​
response
{
  "service": "metacogna-api",
  "version": "1.0.0",
  "status": "ok",
  "endpoints": {
    "health": "/api/health",
    "auth": "/api/auth/login",
    "signup": "/api/signup (admin-only)",
    "ingest": "/api/ingest",
    "search": "/api/search",
    "graph": "/api/graph",
    "chat": "/api/chat"
  }
}

​
GET /api/health

Health check endpoint.
​
response
{
  "status": "ok",
  "timestamp": 1704067200000,
  "service": "metacogna"
}

​
Authentication

​
POST /api/auth/login

User login with SHA-256 hashed credentials.
​
request
{
  "username": "testuser",
  "password": "sha256-hashed-password"
}
Password must be SHA-256 hashed: SHA256(username + password)
​
response
{
  "success": true,
  "user": {
    "id": "user-uuid",
    "username": "testuser",
    "email": "[email protected]",
    "name": "Test User",
    "isAdmin": false,
    "goals": "Learn RAG systems",
    "lastLogin": 1704067200000
  },
  "token": "session-token"
}
Session cookie is set automatically with 7-day expiry.

​
POST /api/signup

Admin-only endpoint to create new users.
Only admin users can create new accounts. Non-admin users see “Contact administrator” message.
​
request
multipart/form-data
name=Alice Johnson
[email protected]
password=SecurePass123!
goals=Build RAG system for research papers
files[]=<file1.md>
files[]=<file2.pdf>
​
response
{
  "success": true,
  "userId": "user-20250101-uuid",
  "goalsSummary": "Build RAG system, learn vector databases",
  "filesUploaded": 2,
  "files": [
    {
      "id": "doc-uuid-1",
      "filename": "file1.md",
      "r2Key": "users/user-uuid/documents/doc-uuid-1-file1.md",
      "uploadedAt": 1704067200000
    }
  ]
}
Notes:
  • Goals are automatically summarized using Workers AI
  • Files are uploaded to R2: users/{userId}/documents/{docId}-{filename}
  • User ID is generated as UUID v4

​
Documents

​
POST /api/ingest

Upload documents for indexing.
​
request
multipart/form-data
userId=user-uuid
file=<document.pdf>
metadata={"author": "Alice", "category": "Research"}
​
response
{
  "success": true,
  "documentId": "doc-uuid",
  "r2Key": "users/user-uuid/documents/doc-uuid-document.pdf",
  "chunks": 28,
  "graphNodes": 12,
  "status": "indexed"
}
Pipeline Stages:
  1. Chunking (0-29%) - Text splitting into semantic chunks
  2. Embedding (30-59%) - Vector embedding generation
  3. Graph Extraction (60-89%) - Entity and relationship extraction
  4. Finalizing (90-100%) - Final indexing

​
GET /api/documents

Get all documents for authenticated user.
​
response
{
  "documents": [
    {
      "id": "doc-001",
      "userId": "user-uuid",
      "title": "RAG System Overview",
      "r2Key": "users/user-uuid/documents/doc-001-overview.md",
      "uploadedAt": 1704067200000,
      "status": "indexed",
      "progress": 100,
      "chunkCount": 42,
      "metadata": {
        "author": "Alice Chen",
        "category": "Research",
        "tags": "RAG, Embeddings"
      }
    }
  ]
}
Status Values:
  • processing - Ingestion in progress
  • indexed - Successfully indexed
  • error - Ingestion failed

​
POST /api/documents/reindex

Reindex all documents (maintenance operation).
​
response
{
  "success": true,
  "documentsReindexed": 42
}

​
DELETE /api/documents/purge-errors

Remove all documents with error status.
​
response
{
  "success": true,
  "documentsPurged": 3
}

​
GET /api/search

Semantic vector search.
​
query
string
Search query string
​
userId
string
User ID for filtering
​
topK
number
default:"5"
Number of results to return
​
response
{
  "results": [
    {
      "id": "chunk-uuid",
      "documentId": "doc-uuid",
      "text": "Retrieval-Augmented Generation...",
      "score": 0.89,
      "metadata": {
        "documentTitle": "RAG Overview",
        "chunkIndex": 5
      }
    }
  ]
}

​
Knowledge Graph

​
GET /api/graph

Get knowledge graph nodes and relationships.
​
userId
string
User ID for filtering
​
response
{
  "nodes": [
    {
      "id": "entity-1",
      "label": "Artificial Intelligence",
      "type": "concept",
      "documentIds": ["doc-1", "doc-2"]
    }
  ],
  "edges": [
    {
      "source": "entity-1",
      "target": "entity-2",
      "type": "relates_to",
      "strength": 0.85
    }
  ]
}

​
Rate Limiting

Chat endpoint has rate limiting:
  • Limit: 10 requests per minute per user
  • Headers: X-RateLimit-Remaining, X-RateLimit-Reset
  • Status: 429 when limit exceeded

​
Error Responses

All errors follow this format: 
{
  "error": "Error message",
  "success": false
}
Common status codes:
  • 400 - Bad Request (validation errors)
  • 401 - Unauthorized (authentication required)
  • 404 - Not Found
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error