API Documentation

Base URL

http://localhost:8000

Authentication

Requests can be made as anonymous (no key) or as a member (with API key). Members get higher rate limits.

# Via X-API-Key header
curl -H "X-API-Key: oa-..." http://localhost:8000/chat

# Via Authorization Bearer header
curl -H "Authorization: Bearer oa-..." http://localhost:8000/chat

POST/chat— Chat (JSON response)

Parameters

Request

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: oa-your-key" \
  -d '{
    "message": "What is machine learning?",
    "model": "smollm:latest"
  }'

Response

{
  "user": "user_abc123",
  "tier": "member",
  "response": {
    "model": "smollm:latest",
    "response": "Machine learning is...",
    "done": true
  }
}

POST/chat/stream— Chat (Streaming)

Same parameters as /chat. Returns newline-delimited JSON.

Request

curl -X POST "http://localhost:8000/chat/stream" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "model": "smollm:latest"}'

Response

{"model":"smollm:latest","response":"Hello","done":false}
{"model":"smollm:latest","response":"!","done":false}
{"model":"smollm:latest","response":"","done":true}

GET/api/status— Server Status

Request

curl "http://localhost:8000/api/status"

Response

{
  "server": { "uptime_seconds": 3600, "uptime_human": "1h 0m" },
  "system": {
    "ram_total_gb": 8.0, "ram_used_gb": 5.2,
    "ram_percent": 65.0, "cpu_percent": 12.5
  },
  "ollama": {
    "online": true,
    "models": [{ "name": "smollm:latest", "size_gb": 1.0 }]
  },
  "usage": {
    "total_requests": 142,
    "active_anonymous_ips": 3,
    "anon_rate_limit": "10 req / 60s",
    "member_rate_limit": "30 req / 60s"
  }
}

GET/api/usage— Usage Logs

curl "http://localhost:8000/api/usage?limit=10"

API Key Management

curl -X POST "http://localhost:8000/api/keys?user_id=abc&name=MyKey"

curl "http://localhost:8000/api/keys?user_id=abc"

curl -X DELETE "http://localhost:8000/api/keys/1?user_id=abc"

Error Codes