API Reference
Relevant source files
The following files were used as context for generating this wiki page:
The SecondLayer API is a comprehensive suite of endpoints providing AI-powered legal document analysis, semantic search over court decisions, and legislation retrieval. The system utilizes a "Triple Transport System" supporting Standard MCP (stdio), RESTful HTTP API, and Server-Sent Events (SSE) for remote streaming.
Sources: CLAUDE.md:46-52, mcp_backend/src/http-server.ts:1107-1115
Architecture and Transport
The API operates as a Unified Gateway aggregating 45 MCP tools across three primary servers: mcp_backend (court cases and legal docs), mcp_rada (parliamentary data), and mcp_openreyestr (business registries).
Transport Mechanisms
- HTTP REST: Traditional request-response for tool execution and management.
- SSE (Server-Sent Events): Used for long-running operations and real-time streaming of AI "thinking steps" and progressive results.
- Standard MCP Stdio: Protocol for direct integration with local LLM clients like Claude Desktop.
Sources: CLAUDE.md:54-61, lexwebapp/BUILD_SUMMARY.md:65-71
Unified Gateway Data Flow
The following diagram illustrates how requests are routed through the Unified Gateway to specific service handlers.
The Gateway manages tool discovery and execution across distributed MCP servers.
Sources: CLAUDE.md:63-71, mcp_backend/src/http-server.ts:1020-1040
Authentication and Security
The API employs a dual-authentication strategy to support both web users and automated API clients.
| Auth Type | Implementation | Target Audience |
|---|---|---|
| Bearer Token | SECONDARY_LAYER_KEYS | API Clients / MCP integrations |
| JWT | JSON Web Tokens via Google OAuth | Web application users |
| OAuth 2.0 | RFC 8414 Discovery | ChatGPT/Claude Custom Connectors |
Sources: mcp_backend/src/http-server.ts:125-130, CLAUDE.md:120-123, mcp_backend/src/routes/TEMPLATE_ROUTES_INTEGRATION.md:105-125
Core Endpoints
AI Chat and Tool Execution
These endpoints provide the primary interface for legal analysis and tool interactions.
POST /api/chat: Initiates an agentic LLM loop that streams thinking steps, tool results, and final answers via SSE.POST /api/tools/:toolName: Executes a specific MCP tool. SupportsAccept: text/event-streamfor streaming results.GET /api/tools: Lists all available tools in the registry (44-45 tools depending on gateway configuration).POST /api/tools/batch: Executes multiple tool calls in a single request.
Sources: mcp_backend/src/http-server.ts:914-958, mcp_backend/src/http-server.ts:1003-1100, lexwebapp/BUILD_SUMMARY.md:65-75
Dynamic Template System
Self-learning pipeline for classifying questions and generating prompt templates.
Pipeline for automated template management.
Sources: mcp_backend/src/services/template-system/README.md:10-40, mcp_backend/src/routes/TEMPLATE_ROUTES_INTEGRATION.md:50-65
| Method | Endpoint | Description |
|---|---|---|
POST | /api/templates/classify-question | Determines intent and extracts entities (dates, amounts). |
GET | /api/templates/match | Semantic search for existing templates via Qdrant. |
POST | /api/templates/generate | Generates a new template if match score is low ($0.08 cost). |
PUT | /api/templates/generation/:id/approve | Admin approval for newly generated templates. |
Sources: mcp_backend/src/services/template-system/README.md:195-235, mcp_backend/src/routes/TEMPLATE_ROUTES_INTEGRATION.md:67-85
Billing and Time Tracking
Manages financial operations, credits, and professional time logs.
GET /api/billing/balance: Returns current balance (USD/UAH), spending limits, and pricing tier.POST /api/billing/topup: Initiates a balance top-up via Stripe, Fondy, or Crypto.POST /api/time/timers/start: Starts a billable hour timer for a specific matter.POST /api/invoicing/generate: Generates a PDF invoice from approved time entries.
Sources: mcp_backend/src/http-server.ts:544-570, IMPLEMENTATION_PHASES.md:65-85
SSE Streaming Protocol
For long-running legal research tasks, the API uses a specific event structure.
// Example Event-Stream Format
event: connected
data: {"tool": "search_court_cases", "timestamp": "..."}
event: progress
data: {"message": "Searching ZakonOnline...", "progress": 0.4}
event: complete
data: {"results": [...]}
The system includes a Heartbeat Mechanism every 15 seconds to prevent proxy/gateway timeouts during complex tool executions.
Sources: mcp_backend/src/http-server.ts:1176-1215, mcp_backend/src/http-server.ts:930-940
Admin and System Management
Admin endpoints require JWT authentication with elevated privileges.
GET /api/admin/stats/overview: Aggregated dashboard statistics and revenue charts.GET /api/admin/upload-metrics: Real-time status of the BullMQ upload queue and MinIO storage depth.POST /webhooks/stripe: Public-facing endpoint for Stripe payment events (requires raw body signature verification).
Sources: mcp_backend/src/http-server.ts:880-900, mcp_backend/src/http-server.ts:182-190, deployment/nginx/includes/api-endpoints.conf:15-20
Conclusion
The SecondLayer API Reference defines a robust multi-transport architecture designed for high-availability legal tech applications. By unifying diverse legal data sources under a single MCP Tool Registry and providing detailed cost tracking and streaming capabilities, it serves as the backbone for AI-driven legal workflows.
Sources: CLAUDE.md:63-71, mcp_backend/src/http-server.ts:1107-1115