🔌 API Reference

Locentra OS exposes a full REST API built on FastAPI, enabling easy integration with external tools, scripts, or web UIs.

• 🔗 Base URL:

  http://localhost:8000

• 📘 Swagger Docs:

  http://localhost:8000/docs

---

🧭 API Structure

All endpoints are prefixed with:

/api/

---

📤 POST /api/llm/query

Send a prompt to the model and receive a generated response.

🧾 Request

{
  "prompt": "Explain rollups in Ethereum"
}

✅ Response

{
  "response": "Rollups are a Layer 2 scaling solution that batch transactions..."
}

🧪 Curl Example

curl -X POST http://localhost:8000/api/llm/query \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is Solana?"}'

---

🎓 POST /api/llm/train

Train the model on a new prompt → completion pair.

🧾 Request

{
  "prompt": "What is slippage?",
  "completion": "Slippage refers to the difference between expected and actual execution price."
}

✅ Response

{
  "status": "ok",
  "message": "Training sample processed."
}

🧠 Optional Add-ons (via metadata)

• Semantic vectorization of the prompt

• Tagging (for filtered memory access)

• Dry-run flag (simulate training without execution)

Use this endpoint to feed real-world data into your model — one sample at a time.

---

👤 POST /api/user/create

Registers a new user.

🧾 Request

{
  "username": "alice"
}

Note: email is optional and unused unless extended.

✅ Response

{
  "username": "alice",
  "api_key": "d3f3b38e-42aa-4c9c-9447-b5409b09f123"
}

Used internally by scripts and agents to track prompt provenance or session state.

---

📡 GET /api/system/logs

Streams live logs from backend activity.

✅ Response

[2025-05-19 13:44] Training started: 12 samples
[2025-05-19 13:45] Vector memory updated
[2025-05-19 13:46] Inference: Prompt received from CLI

Supports optional filtering by level and limit: /api/system/logs?level=INFO&limit=100

---

🔒 Authentication

Locentra OS ships with open API endpoints by default to support local-first development.

If you need access control:

• 🔐 Add middleware in: backend/api/middleware/auth.py

• 🔑 Enable token-auth or key-auth in server.py

• 🧱 Use Docker network isolation or NGINX ACLs for perimeter security

Locentra doesn’t lock you in—but it gives you the hooks to lock things down.

---

🧪 Testing & Debugging

You can explore all endpoints via Swagger:

http://localhost:8000/docs

Or test manually with tools like:

• curl (command line)

• httpie

• Postman / Insomnia

• Python scripts using requests

Every call hits the same backend used by the CLI and Web UI — it’s all one engine.