API Endpoints

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.

{
  "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.

{
  "status": "ok",
  "timestamp": 1704067200000,
  "service": "metacogna"
}

Authentication

User login with SHA-256 hashed credentials.

{
  "username": "testuser",
  "password": "sha256-hashed-password"
}

Password must be SHA-256 hashed: SHA256(username + password)

{
  "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. Admin-only endpoint to create new users.

Only admin users can create new accounts. Non-admin users see “Contact administrator” message.

multipart/form-data

name=Alice Johnson
[email protected]
password=SecurePass123!
goals=Build RAG system for research papers
files[]=<file1.md>
files[]=<file2.pdf>

{
  "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.

multipart/form-data

userId=user-uuid
file=<document.pdf>
metadata={"author": "Alice", "category": "Research"}

{
  "success": true,
  "documentId": "doc-uuid",
  "r2Key": "users/user-uuid/documents/doc-uuid-document.pdf",
  "chunks": 28,
  "graphNodes": 12,
  "status": "indexed"
}

Pipeline Stages:

Chunking (0-29%) - Text splitting into semantic chunks
Embedding (30-59%) - Vector embedding generation
Graph Extraction (60-89%) - Entity and relationship extraction
Finalizing (90-100%) - Final indexing

GET /api/documents

Get all documents for authenticated user.

{
  "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).

{
  "success": true,
  "documentsReindexed": 42
}

DELETE /api/documents/purge-errors

Remove all documents with error status.

{
  "success": true,
  "documentsPurged": 3
}

Search

GET /api/search

Semantic vector search.

string

Search query string

string

User ID for filtering

number

default:"5"

Number of results to return

{
  "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.

string

User ID for filtering

{
  "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

Chat Endpoint - Detailed chat API documentation
Backend Worker - Worker implementation details

Getting Started

Gateway API

MetaCogna RAG

MetaCogna.ai Landing

Parti Architecture

Design System

Base URL

Authentication

Endpoints

Health & Debug

GET /

GET /api/health

Authentication

Documents

POST /api/ingest

GET /api/documents

POST /api/documents/reindex

DELETE /api/documents/purge-errors

Search

GET /api/search

Knowledge Graph

GET /api/graph

Rate Limiting

Error Responses

​Base URL

​Authentication

​Endpoints

​Health & Debug

​GET /

​GET /api/health

​Authentication

​POST /api/auth/login

​POST /api/signup

​Documents

​POST /api/ingest

​GET /api/documents

​POST /api/documents/reindex

​DELETE /api/documents/purge-errors

​Search

​GET /api/search

​Knowledge Graph

​GET /api/graph

​Rate Limiting

​Error Responses

​Related Documentation

Base URL

Authentication

Endpoints

Health & Debug

GET /

GET /api/health

Authentication

POST /api/auth/login

POST /api/signup

Documents

POST /api/ingest

GET /api/documents

POST /api/documents/reindex

DELETE /api/documents/purge-errors

Search

GET /api/search

Knowledge Graph

GET /api/graph

Rate Limiting

Error Responses

Related Documentation