Skip to content

reference.md

Latest commit

 

History

History
583 lines (413 loc) · 9.92 KB

reference.md

File metadata and controls

583 lines (413 loc) · 9.92 KB
Raw

API Documentation

KeepAI exposes a REST API at /api/v1 and a WebSocket endpoint at /ws/chat. Live interactive documentation is available at /docs (Swagger) and /redoc (ReDoc).

Base URL

http://localhost:8000/api/v1

WebSocket URL (derived from host):

ws://<host>/ws/chat?token=<jwt>

Authentication

Most endpoints require JWT authentication. Obtain a token via login, then include it in the Authorization header:

Authorization: Bearer <your_access_token>

Health

Liveness

GET /health/live

Always returns 200 if the process is running. No dependencies.

Response 200 OK

{ "status": "ok" }

Readiness

GET /health/ready

Verifies database and Ollama connectivity before accepting traffic.

Response 200 OK

{ "status": "ready", "db": "ok", "llm": "ok" }

Response 503 Service Unavailable

{ "detail": { "status": "unavailable", "db": "could not connect to database" } }

Auth

Register

POST /api/v1/auth/register
Field Type Required Description
email string yes Valid email address
password string yes Password (min 8 chars recommended)
role string no "admin" or "user" (defaults to "user") 
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "securepassword"}'

Response 201 Created

{ "id": 1, "email": "user@example.com", "is_active": true, "role": "user" }

Login

POST /api/v1/auth/login

Uses OAuth2 form data.

Field Type Required Description
username string yes User's email
password string yes User's password 
curl -X POST http://localhost:8000/api/v1/auth/login \
  -F "username=user@example.com" \
  -F "password=securepassword"

Response 200 OK

{ "access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer" }

Token expires in 30 minutes by default.

Prompts

Generate

POST /api/v1/prompts
Field Type Required Description
prompt_text string yes The prompt to send to the LLM
model_name string no Model name. Defaults to OLLAMA_MODEL
system_prompt string no System instructions
task_type string no Task type for model routing
temperature float no Sampling temperature (0.0-2.0)
top_p float no Nucleus sampling (0.0-1.0)
max_tokens int no Maximum tokens to generate 
curl -X POST http://localhost:8000/api/v1/prompts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"prompt_text": "Explain ML in 3 points.", "model_name": "llama3"}'

Response 201 Created

{
  "id": 42,
  "prompt_text": "Explain ML in 3 points.",
  "response_text": "- Machine learning is a subset of AI...",
  "model_name": "llama3",
  "processing_time_ms": 4523,
  "meta_data": {},
  "created_at": "2026-01-15T10:30:00Z",
  "user_id": 1
}

Stream

POST /api/v1/prompts/stream

Same body as Generate. Returns SSE stream. Not persisted.

data: Machine
data:  learning
data: [DONE]

List

GET /api/v1/prompts?skip=0&limit=20
Param Type Default Description
skip int 0 Records to skip
limit int 20 Max records per page

Response 200 OK

{ "items": [...], "total": 1, "skip": 0, "limit": 20 }

Get by ID

GET /api/v1/prompts/{prompt_id}

Scoped to the authenticated user.

Extract Invoice

POST /api/v1/extract-invoice
Field Type Required Description
text_content string yes Raw invoice text
model_name string no Model name

Returns structured JSON with invoice_number, vendor_name, date, items, total_amount, currency.

Chat (Multi-turn)

Generate

POST /api/v1/chat
Field Type Required Description
messages array yes [{role, content}] roles: user/assistant/system
model_name string no Model name
system_prompt string no Prepended as system message
temperature float no 0.0-2.0
top_p float no 0.0-1.0
max_tokens int no Max tokens

Stream

POST /api/v1/chat/stream

Same body as Chat. Returns SSE stream.

Conversations

Create

POST /api/v1/conversations
{ "title": "My conversation", "model_name": "llama3" }

List

GET /api/v1/conversations?skip=0&limit=20

Returns conversations with message_count.

Get

GET /api/v1/conversations/{conversation_id}

Returns conversation with all messages.

Update Title

PUT /api/v1/conversations/{conversation_id}/title?title=New+Title

Delete

DELETE /api/v1/conversations/{conversation_id}

Chat in Conversation

POST /api/v1/conversations/{conversation_id}/chat
{ "message": "Hello", "model_name": "llama3" }

WebSocket

Connect

ws://<host>/ws/chat?token=<jwt>

Message Types

Send: list_conversations

{ "type": "list_conversations" }

Response: { "type": "conversations", "items": [...] }

Send: get_conversation

{ "type": "get_conversation", "conversation_id": 1 }

Response: { "type": "conversation", "id": 1, "title": "...", "messages": [...], "user_id": 1, "created_at": "...", "updated_at": "..." }

Send: chat

{
  "type": "chat",
  "conversation_id": 1,
  "message": "Hello!",
  "model_name": "llama3",
  "system_prompt": "Be helpful",
  "temperature": 0.7,
  "top_p": 0.9
}

Response: { "type": "chat_response", "response_text": "...", "conversation_id": 1 }

Send: delete_conversation

{ "type": "delete_conversation", "conversation_id": 1 }

Response: { "type": "conversation_deleted", "conversation_id": 1 }

Send: ping

{ "type": "ping" }

Response: { "type": "pong" }

API Keys

List

GET /api/v1/api-keys

Create

POST /api/v1/api-keys
{ "name": "My Key" }

Response 201 Created

{ "id": 1, "name": "My Key", "key": "ka_...", "is_active": true, "created_at": "..." }

The key value is only shown once at creation.

Revoke

DELETE /api/v1/api-keys/{key_id}

Analytics

User Stats

GET /api/v1/analytics/stats?days=7
Param Type Default Description
days int null (all time) Number of days to look back

Response 200 OK

{
  "total_requests": 150,
  "total_processing_time_ms": 450000,
  "avg_processing_time_ms": 3000.0,
  "requests_by_model": { "llama3": 120, "mistral": 30 },
  "requests_by_action": { "prompt": 100, "chat": 50 },
  "requests_today": 12
}

Admin: All User Stats

GET /api/v1/analytics/admin/user-stats

Returns per-user stats for all users. Requires admin.

Documents

List

GET /api/v1/documents

Upload

POST /api/v1/documents/upload

Multipart form with file field.

Get

GET /api/v1/documents/{document_id}

Returns document with content_text and chunk_count.

Delete

DELETE /api/v1/documents/{document_id}

Search (GET)

GET /api/v1/documents/search?q=keyword&top_k=5
Param Type Default Description
q string required Search query
top_k int 5 Max results (max 50)

Search (POST)

POST /api/v1/documents/search
{ "query": "keyword", "top_k": 5 }

Query with LLM

POST /api/v1/documents/query
{ "query": "What is this document about?", "top_k": 5 }

Response 200 OK

{ "results": [...], "response": "Found 5 relevant documents" }

Generate Embeddings

POST /api/v1/documents/{document_id}/embed

Response 200 OK

{ "status": "embedded" }

Models

List

GET /api/v1/models

Returns models available in Ollama with name, size, digest, details.

Pull

POST /api/v1/models/pull
Field Type Required Description
name string yes Model name, e.g., "llama3"
insecure boolean no Allow insecure connections

Requires models:manage permission (admin).

Delete

DELETE /api/v1/models/{model_name}

Requires models:manage permission (admin).

Admin

List Users

GET /api/v1/admin/users?skip=0&limit=100

Requires users:read permission (admin).

List All Prompts

GET /api/v1/admin/all-prompts?skip=0&limit=100

Requires prompts:read_all permission (admin).

Error Responses

401 Unauthorized

{ "detail": "Not authenticated" }

403 Forbidden

{ "detail": "Insufficient permissions" }

404 Not Found

{ "detail": "Resource not found" }

422 Validation Error

{
  "detail": [
    { "loc": ["body", "email"], "msg": "field required", "type": "value_error.missing" }
  ]
}

429 Rate Limit Exceeded

{ "detail": "Rate limit exceeded. Please slow down." }

500 Internal Server Error

{ "detail": "Internal server error" }

Rate Limiting

Rate limiting is implemented via slowapi (configurable via RATE_LIMIT_LLM env var, default: 20/minute). Limits are applied per user (JWT email) or fall back to client IP. See Configuration for details.

Changelog

See Changelog for version history.