API Documentation

Base URL

http://localhost:3000/api/v1

Authentication

Currently, authentication is handled via:

Tenant ID: Required in all requests (query params or body)
App ID: Required in all requests (query params or body)
Roles: Required for routing requests (determines access)

Routing APIs

POST /api/v1/route

Main routing endpoint - determines the best route for a user query.

Request Body:

{
  "tenant_id": "tenant-001",
  "app_id": "app-001",
  "roles": ["user", "admin"],
  "query": "How do I troubleshoot network issues?",
  "context": {
    "session_id": "session-123",
    "user_id": "user-456"
  },
  "service_type_hint": "SEARCH",
  "require_explanation": false,
  "top_k": 3,
  "min_confidence": 0.7,
  "cache_control": {
    "force_refresh": false,
    "max_cache_age_seconds": 3600,
    "min_confidence": 0.7,
    "invalidate_on_mismatch": true,
    "source_id_hint": "network-troubleshooting"
  },
  "previous_request_feedback": {
    "previous_cache_key": "cache-key-123",
    "was_correct": true,
    "correct_source_id": "network-troubleshooting"
  }
}

Response:

{
  "success": true,
  "data": {
    "routes": [
      {
        "source_id": "network-troubleshooting",
        "source_type": "vector_db",
        "service_type": "SEARCH",
        "source_name": "Network Troubleshooting",
        "connection_info": {
          "collection_name": "network-troubleshooting",
          "connection_type": "vector_db"
        },
        "context_to_pass": {
          "hierarchy_path": {
            "root_id": "document-search-service",
            "root_type": "SEARCH",
            "levels": [
              {
                "level": 0,
                "id": "document-search-service",
                "name": "Document Search Service",
                "type": "Service"
              },
              {
                "level": 1,
                "id": "troubleshooting-category",
                "name": "Troubleshooting Guides",
                "type": "Category"
              },
              {
                "level": 2,
                "id": "network-troubleshooting",
                "name": "Network Troubleshooting",
                "type": "Collection"
              }
            ]
          }
        },
        "confidence_score": 0.85,
        "ranking_score": 0.90
      }
    ],
    "primary_route": { ... },
    "confidence": 0.85,
    "decision_path": "HIERARCHY_TRAVERSAL",
    "explanation": "...",
    "latency_ms": 145
  }
}

Error Responses:

400: Invalid request (validation errors)
403: Access denied (role validation failed)
404: No match found (confidence below threshold)
500: Internal server error

POST /api/v1/route/batch

Batch routing for multiple queries.

Request Body:

{
  "queries": [
    {
      "tenant_id": "tenant-001",
      "app_id": "app-001",
      "roles": ["user"],
      "query": "Query 1"
    },
    {
      "tenant_id": "tenant-001",
      "app_id": "app-001",
      "roles": ["admin"],
      "query": "Query 2"
    }
  ]
}

Response:

{
  "success": true,
  "data": [
    {
      "success": true,
      "query": "Query 1",
      "data": { ... }
    },
    {
      "success": false,
      "query": "Query 2",
      "error": "Error message"
    }
  ]
}

Hierarchy Management APIs

GET /api/v1/hierarchy/nodes

List all nodes (with optional filtering).

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier
level (optional): Filter by level (0, 1, 2)
parent_id (optional): Filter by parent ID
status (optional): Filter by status (active, inactive, maintenance)
include_source_texts (optional): Include source texts in response (true/false)

Response:

{
  "success": true,
  "data": {
    "nodes": [
      {
        "id": "node-123",
        "type": "Service",
        "level": 0,
        "name": "Document Search Service",
        "description": "...",
        "source_texts": { ... }  // If include_source_texts=true
      }
    ],
    "total": 10
  }
}

GET /api/v1/hierarchy/nodes/:node_id

Get a specific node.

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier
include_source_texts (optional): Include source texts (true/false)

Response:

{
  "success": true,
  "data": {
    "id": "node-123",
    "type": "Service",
    "level": 0,
    "name": "Document Search Service",
    "description": "...",
    "service_type": "SEARCH",
    "service_context": { ... },
    "source_texts": { ... }  // If include_source_texts=true
  }
}

POST /api/v1/hierarchy/nodes

Create a new node.

Request Body:

{
  "id": "new-node-123",
  "type": "Service",
  "level": 0,
  "tenant_id": "tenant-001",
  "app_id": "app-001",
  "parent_id": null,
  "name": "New Service",
  "description": "Service description",
  "service_type": "SEARCH",
  "service_context": {
    "detailed_description": "...",
    "routing_keywords": {
      "boost_keywords": ["search", "find"],
      "penalty_keywords": ["api"],
      "boost_value": 0.2,
      "penalty_value": -0.15
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "new-node-123",
    "type": "Service",
    "level": 0,
    "name": "New Service",
    "created_at": "2025-01-13T10:00:00Z"
  }
}

PUT /api/v1/hierarchy/nodes/:node_id

Update a node (partial update supported).

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier

Request Body:

{
  "name": "Updated Name",
  "description": "Updated description",
  "service_context": {
    "routing_keywords": {
      "boost_keywords": ["search", "find", "new-keyword"]
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "node-123",
    "type": "Service",
    "level": 0,
    "name": "Updated Name",
    "updated_at": "2025-01-13T10:00:00Z"
  }
}

Admin APIs

GET /api/v1/admin/hierarchy/nodes

List all nodes (admin endpoint with more details).

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier
level (optional): Filter by level
include_source_texts (optional): Include source texts

Response: Same as public GET /api/v1/hierarchy/nodes

GET /api/v1/admin/hierarchy/nodes/:nodeId

Get a specific node (admin endpoint).

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier
include_source_texts (optional): Include source texts

Response: Same as public GET /api/v1/hierarchy/nodes/:node_id

PUT /api/v1/admin/hierarchy/nodes/:nodeId

Update node (full update).

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier

Request Body: Full node object

Response: Updated node

PATCH /api/v1/admin/hierarchy/nodes/:nodeId

Update node (partial update).

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier

Request Body: Partial node object

Response: Updated node

DELETE /api/v1/admin/hierarchy/nodes/:nodeId

Delete a node (soft delete by default).

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier
hard_delete (optional): true for hard delete

Response:

{
  "success": true,
  "message": "Node deleted successfully"
}

GET /api/v1/admin/hierarchy/nodes/:nodeId/children

Get children of a node.

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier

Response:

{
  "success": true,
  "data": {
    "children": [
      {
        "id": "child-1",
        "type": "Category",
        "level": 1,
        "name": "Category 1"
      }
    ]
  }
}

GET /api/v1/admin/hierarchy/nodes/:nodeId/structure

Get hierarchy structure for a root node.

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier

Response:

{
  "success": true,
  "data": {
    "root": { ... },
    "children": {
      "1": [ ... ],
      "2": [ ... ]
    }
  }
}

Source Texts APIs

GET /api/v1/admin/hierarchy/nodes/:nodeId/source-texts

Get source texts for a node (for frontend editing).

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier

Response:

{
  "success": true,
  "data": {
    "node_id": "node-123",
    "source_texts": ["text1", "text2", ...],
    "source_weights": [0.1, 0.35, ...],
    "text_sources": [
      {
        "index": 0,
        "source": "Document Search Service",
        "field_path": "name",
        "weight": 0.1,
        "included": true,
        "ignore_reason": null
      }
    ],
    "embedding_config": {
      "ignore_fields": ["none"]
    },
    "is_edited": false,
    "last_embedded_at": "2025-01-13T10:00:00Z",
    "embedding_version": 1
  }
}

PUT /api/v1/admin/hierarchy/nodes/:nodeId/source-texts

Update source texts and regenerate embeddings.

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier

Request Body:

{
  "texts": ["text1", "text2"],  // Optional: Direct text update
  "weights": [0.5, 0.5],       // Optional: Corresponding weights
  "embedding_config": {
    "ignore_fields": ["service_context.detailed_description"]
  },
  "regenerate_embeddings": true,  // Optional: Control regeneration (default: true)
  "update_only_config": false     // Optional: Only update config (default: false)
}

Response:

{
  "success": true,
  "message": "Source texts updated and embeddings regenerated",
  "data": {
    "node": { ... },
    "source_texts": { ... }
  }
}

POST /api/v1/admin/hierarchy/nodes/:nodeId/source-texts/regenerate

Regenerate embeddings from existing source texts.

Query Parameters:

tenant_id (required): Tenant identifier
app_id (required): Application identifier

Request Body (optional):

{
  "embedding_config": {
    "ignore_fields": ["service_context.detailed_description"]
  }
}

Response:

{
  "success": true,
  "message": "Embeddings regenerated from source texts",
  "data": {
    "node": { ... },
    "source_texts": { ... }
  }
}

Cache Management APIs

GET /api/v1/cache/entries

List cache entries (with optional filtering).

Query Parameters:

tenant_id (optional): Filter by tenant
app_id (optional): Filter by app
limit (optional): Max results (default: 100)

Response:

{
  "success": true,
  "data": {
    "entries": [
      {
        "cache_key": "cache-key-123",
        "tenant_id": "tenant-001",
        "app_id": "app-001",
        "query": "How do I...",
        "confidence_score": 0.85,
        "timestamp": "2025-01-13T10:00:00Z"
      }
    ],
    "total": 10
  }
}

POST /api/v1/cache/clear

Clear all caches or caches for specific tenant/app.

Request Body:

{
  "tenant_id": "tenant-001",  // Optional
  "app_id": "app-001"         // Optional
}

Response:

{
  "success": true,
  "message": "Caches cleared",
  "data": {
    "tenant_id": "tenant-001",
    "app_id": "app-001",
    "deleted_count": 150
  }
}

POST /api/v1/cache/invalidate

Invalidate specific cache pattern or by tenant/app.

Request Body:

{
  "pattern": "cache-pattern-*",  // Optional
  "tenant_id": "tenant-001",     // Optional
  "app_id": "app-001",           // Optional
  "reason": "Data updated"
}

Response:

{
  "success": true,
  "data": {
    "pattern": "cache-pattern-*",
    "tenant_id": "tenant-001",
    "app_id": "app-001",
    "deleted": 25,
    "reason": "Data updated"
  }
}

Health & Metrics APIs

GET /api/v1/health

Health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": "2025-01-13T10:00:00Z",
  "components": {
    "hierarchy": "up",
    "redis": "up",
    "llm": "up"
  }
}

GET /api/v1/metrics

System metrics endpoint.

Response:

{
  "success": true,
  "data": {
    "hierarchy": {
      "services": {
        "total": 5,
        "active": 4,
        "inactive": 1,
        "by_type": {
          "SEARCH": 2,
          "SQL": 2,
          "REST": 1
        }
      },
      "categories": {
        "total": 10,
        "active": 9,
        "inactive": 1
      },
      "collections": {
        "total": 25,
        "active": 23,
        "inactive": 2
      }
    },
    "cache": {
      "total_entries": 150,
      "hit_rate": 0.85,
      "miss_rate": 0.15
    },
    "embedding": {
      "cache_hits": 500,
      "cache_misses": 50
    },
    "access_control": {
      "cache_hits": 300,
      "cache_misses": 20
    },
    "timestamp": "2025-01-13T10:00:00Z"
  }
}

Error Responses

All endpoints return errors in this format:

{
  "success": false,
  "error": "Error message",
  "details": [  // Optional: Validation errors
    {
      "field": "query",
      "message": "Query is required"
    }
  ]
}

HTTP Status Codes:

200: Success
400: Bad Request (validation errors)
403: Forbidden (access denied)
404: Not Found
500: Internal Server Error
503: Service Unavailable

Rate Limiting

Currently, no rate limiting is implemented. Consider adding rate limiting for production use.

Pagination

List endpoints support pagination via query parameters:

limit: Number of results (default: 100, max: 1000)
offset: Number of results to skip (default: 0)

Examples

Example 1: Route a Query

curl -X POST http://localhost:3000/api/v1/route \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant-001",
    "app_id": "app-001",
    "roles": ["user"],
    "query": "How do I troubleshoot network issues?"
  }'

Example 2: Get Node with Source Texts

curl "http://localhost:3000/api/v1/hierarchy/nodes/node-123?tenant_id=tenant-001&app_id=app-001&include_source_texts=true"

Example 3: Update Source Texts

curl -X PUT "http://localhost:3000/api/v1/admin/hierarchy/nodes/node-123/source-texts?tenant_id=tenant-001&app_id=app-001" \
  -H "Content-Type: application/json" \
  -d '{
    "embedding_config": {
      "ignore_fields": ["service_context.detailed_description"]
    },
    "regenerate_embeddings": true
  }'