@cortexa/core 1.1.0 → 1.1.1

package/README.md

@@ -23,6 +23,7 @@
 - [Architecture](#architecture)
 - [Supported Databases](#supported-databases)
 - [CLI Reference](#cli-reference)
+- [REST API](#rest-api)
 - [Configuration](#configuration)
 - [Requirements](#requirements)
 - [Contributing](#contributing)
@@ -307,6 +308,85 @@ npm install @powersync/mysql-zongji
 | `cortexa actions` | View and manage action recommendations |
 | `cortexa explain <type> <id>` | AI explanation of anomaly, insight, or event |
 | `cortexa ask "<question>"` | Ask a natural language question |
+| `cortexa serve` | Start REST API server (`--port`, `--host`) |
+
+## REST API
+
+Start the HTTP server to access Cortexa from any language (Python, Go, Ruby, etc.):
+
+```bash
+npx cortexa serve
+# Cortexa API running at http://127.0.0.1:3210
+```
+
+Options: `--port <port>` (default: 3210), `--host <host>` (default: 127.0.0.1), `--no-cors`.
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/status` | Connection status |
+| GET | `/api/entities` | List classified entities |
+| GET | `/api/relationships` | List entity relationships |
+| GET | `/api/events` | List change events (`?entity=`, `?last=`) |
+| GET | `/api/baselines` | Learned rate baselines |
+| GET | `/api/anomalies` | Detected anomalies (`?severity=`, `?entity=`) |
+| GET | `/api/insights` | State analysis insights (`?entity=`, `?severity=`) |
+| GET | `/api/transitions` | Transition statistics (`?entity=`) |
+| GET | `/api/correlations` | Cross-entity correlations |
+| GET | `/api/distributions` | Value distributions (`?entity=`) |
+| GET | `/api/graph` | Knowledge graph summary |
+| GET | `/api/graph/export` | Full graph as JSON |
+| GET | `/api/graph/entity/:name` | Entity intelligence |
+| GET | `/api/actions` | Recommendations (`?status=`, `?action=`) |
+| POST | `/api/discover` | Trigger schema discovery |
+| POST | `/api/explain` | AI explanation (`{ type, id }`) |
+| POST | `/api/ask` | Natural language question (`{ question }`) |
+| POST | `/api/watch` | Start watching (`{ interval, once }`) |
+| POST | `/api/unwatch` | Stop watching |
+| POST | `/api/actions/:id/approve` | Approve recommendation |
+| POST | `/api/actions/:id/reject` | Reject recommendation |
+
+All responses return `{ ok: boolean, data?: ..., error?: string }`.
+
+### Examples
+
+```bash
+# Get anomalies
+curl http://localhost:3210/api/anomalies?severity=high
+
+# Ask a question
+curl -X POST http://localhost:3210/api/ask \
+  -H "Content-Type: application/json" \
+  -d '{"question": "Why did order activity spike today?"}'
+
+# Explain an anomaly
+curl -X POST http://localhost:3210/api/explain \
+  -H "Content-Type: application/json" \
+  -d '{"type": "anomaly", "id": 1}'
+```
+
+```python
+# Python example
+import requests
+
+r = requests.get("http://localhost:3210/api/anomalies", params={"severity": "high"})
+print(r.json()["data"])
+
+r = requests.post("http://localhost:3210/api/ask", json={"question": "Are orders healthy?"})
+print(r.json()["data"]["answer"])
+```
+
+### Programmatic usage
+
+```ts
+import { CortexaServer } from '@cortexa/core';
+
+const server = new CortexaServer(config, { port: 3210, cors: true });
+await server.start();
+// ... later
+await server.stop();
+```
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexa/core",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "The intelligence layer that turns any database into a self-analyzing, self-explaining system.",
   "type": "module",
   "main": "./dist/index.cjs",