Merge pull request #23 from vcon-dev/VCON-254-docs-for-newly-created-rest-api

Add REST API documentation

Author: pavanputhra

README.md

@@ -372,6 +372,54 @@ curl -X DELETE http://127.0.0.1:3000 \
 
 See [MCP Streamable HTTP Specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) for protocol details.
 
+## REST API
+
+When running in HTTP transport mode, the server also exposes a RESTful HTTP API for vCon operations, designed for programmatic integration with external systems.
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v1/health` | Health check (no auth required) |
+| `POST` | `/api/v1/vcons` | Create/ingest a single vCon |
+| `POST` | `/api/v1/vcons/batch` | Batch ingest up to 100 vCons |
+| `GET` | `/api/v1/vcons` | List recent vCons |
+| `GET` | `/api/v1/vcons/:uuid` | Get a vCon by UUID |
+| `DELETE` | `/api/v1/vcons/:uuid` | Delete a vCon |
+
+### Configuration
+
+```bash
+# REST API settings (optional - defaults work for most cases)
+REST_API_BASE_PATH=/api/v1     # Base path for endpoints
+REST_API_ENABLED=true          # Enable/disable REST API
+
+# API Key Authentication
+VCON_API_KEYS=key1,key2        # Comma-separated valid API keys
+API_AUTH_REQUIRED=true         # Set to false to disable auth
+```
+
+### Quick Example
+
+```bash
+# Health check
+curl http://localhost:3000/api/v1/health
+
+# Create a vCon (requires API key)
+curl -X POST http://localhost:3000/api/v1/vcons \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: your-api-key" \
+  -d '{"vcon":"0.3.0","subject":"Support Call","parties":[{"name":"Agent","tel":"+1111"}]}'
+
+# Batch create
+curl -X POST http://localhost:3000/api/v1/vcons/batch \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: your-api-key" \
+  -d '[{"vcon":"0.3.0","parties":[{"name":"A","tel":"+1"}]},{"vcon":"0.3.0","parties":[{"name":"B","tel":"+2"}]}]'
+```
+
+See the complete [REST API Reference](docs/api/rest-api.md) for detailed documentation.
+
 ## Available MCP Tools
 
 ### 1. **create_vcon**
@@ -865,6 +913,7 @@ vcon-mcp/
 
 ### API Reference
 
+- **[REST API](docs/api/rest-api.md)** - HTTP REST API for vCon ingestion
 - **[Tools API](docs/api/tools.md)** - MCP tools reference
 - **[Prompts API](docs/api/prompts.md)** - MCP prompts reference
 - **[Resources API](docs/api/resources.md)** - MCP resources reference

docs/.vitepress/config.ts

@@ -78,6 +78,7 @@ export default defineConfig({
           text: 'API Reference',
           items: [
             { text: 'Overview', link: '/api/' },
+            { text: 'REST API', link: '/api/rest-api' },
             { text: 'MCP Tools', link: '/api/tools' },
             { text: 'MCP Resources', link: '/api/resources' },
             { text: 'MCP Prompts', link: '/api/prompts' },

docs/SUMMARY.md

@@ -16,6 +16,7 @@
 ## API Reference
 
 * [Overview](api/index.md)
+* [REST API](api/rest-api.md)
 * [MCP Tools](api/tools.md)
 * [MCP Resources](api/resources.md)
 * [MCP Prompts](api/prompts.md)

docs/api/index.md

@@ -10,6 +10,21 @@ The vCon MCP Server provides a comprehensive API for managing virtual conversati
 
 ## API Components
 
+### 🌐 [REST API](./rest-api.md)
+
+HTTP REST API for vCon ingestion:
+
+- **POST /vcons** - Create/ingest a single vCon
+- **POST /vcons/batch** - Batch ingest up to 100 vCons
+- **GET /vcons/:uuid** - Get a vCon by UUID
+- **GET /vcons** - List recent vCons
+- **DELETE /vcons/:uuid** - Delete a vCon
+- **GET /health** - Health check endpoint
+
+[View REST API Reference →](./rest-api.md)
+
+---
+
 ### 🛠️ [Tools](./tools.md)
 
 20+ MCP tools for vCon operations:
@@ -168,32 +183,54 @@ const prompt = await getPrompt("find_by_exact_tags", {
 
 ## Architecture
 
-### MCP Protocol Flow
+### Protocol Flow
 
 ```
-┌─────────────┐
-│   Client    │ (Claude Desktop, Custom Client)
-│  (MCP SDK)  │
-└──────┬──────┘
-       │ MCP Protocol (stdio/HTTP)
-       │
-┌──────▼──────┐
-│   vCon MCP  │
-│    Server   │
-└──────┬──────┘
-       │
-       ├─── Tools ────────┐
-       │                  │
-       ├─── Resources ────┤
-       │                  │
-       ├─── Prompts ──────┤
-       │                  │
-       └─── Database ─────┘
-              │
-       ┌──────▼───────┐
-       │  PostgreSQL  │
-       │  (Supabase)  │
-       └──────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│                        Clients                               │
+├─────────────────────────────────┬────────────────────────────┤
+│   AI Assistants (MCP)           │   External Systems (REST)  │
+│   (Claude Desktop, Custom)      │   (Integrations, Pipelines)│
+└───────────────┬─────────────────┴──────────────┬─────────────┘
+                │ MCP (stdio/HTTP)                │ HTTP/JSON
+                │                                 │
+┌───────────────▼─────────────────────────────────▼────────────┐
+│                     vCon MCP Server                          │
+│  ┌──────────────────────────┬───────────────────────────┐    │
+│  │   MCP Handlers           │   REST API                │    │
+│  │  - Tools (30+)           │  - POST /vcons            │    │
+│  │  - Resources             │  - POST /vcons/batch      │    │
+│  │  - Prompts               │  - GET /vcons/:uuid       │    │
+│  │                          │  - GET /vcons             │    │
+│  │                          │  - DELETE /vcons/:uuid    │    │
+│  │                          │  - GET /health            │    │
+│  └────────────┬─────────────┴────────────┬──────────────┘    │
+│               │                          │                   │
+│  ┌────────────▼──────────────────────────▼──────────────┐    │
+│  │               VCon Service                           │    │
+│  │  - Lifecycle hooks (beforeCreate, afterCreate, ...)  │    │
+│  │  - Validation                                        │    │
+│  │  - Metrics                                           │    │
+│  └────────────────────────┬─────────────────────────────┘    │
+│                           │                                  │
+│  ┌────────────────────────▼─────────────────────────────┐    │
+│  │               Plugin Manager                         │    │
+│  │  - Privacy plugins                                   │    │
+│  │  - Access control                                    │    │
+│  │  - Custom extensions                                 │    │
+│  └────────────────────────┬─────────────────────────────┘    │
+│                           │                                  │
+└───────────────────────────┼──────────────────────────────────┘
+                            │ Supabase Client
+                            │
+                 ┌──────────▼───────────┐
+                 │      PostgreSQL      │
+                 │      (Supabase)      │
+                 │                      │
+                 │  - vCon Tables       │
+                 │  - pgvector          │
+                 │  - GIN/GiST Indexes  │
+                 └──────────────────────┘
 ```
 
 ### Data Flow
@@ -301,19 +338,6 @@ For production deployments:
 
 ---
 
-## Rate Limits
-
-Default rate limits (configurable):
-
-| Operation Type | Limit |
-|---------------|-------|
-| Search operations | 100/min |
-| Create operations | 50/min |
-| Other operations | 200/min |
-| Embedding generation | 10/min |
-
----
-
 ## Error Handling
 
 All API responses include error information:
@@ -332,7 +356,6 @@ interface ErrorResponse {
 - `NOT_FOUND` - vCon or resource not found
 - `DATABASE_ERROR` - Database operation failed
 - `PERMISSION_DENIED` - Insufficient permissions
-- `RATE_LIMIT_EXCEEDED` - Too many requests
 
 ---