Skip to main content

​
HTTP API

Run sxth-mind as an HTTP service.

​
Starting the Server

pip install sxth-mind[api]
sxth-mind serve --adapter sales --port 8000
Options:
  • --adapter — Adapter to use (sales, habits, learning)
  • --port — Port to bind (default: 8000)
  • --host — Host to bind (default: 0.0.0.0)
  • --storage — Storage backend (memory, sqlite)
  • --db-path — SQLite database path

​
Endpoints

​
Health Check

GET /health
Response: 
{
  "status": "healthy",
  "adapter": "sales",
  "storage": "MemoryStorage"
}

​
Chat

POST /chat
Send a message and get a response. State is managed automatically. Request: 
{
  "user_id": "user_123",
  "message": "Working on the Acme deal",
  "project_id": "deal_acme"  // optional
}
Response: 
{
  "response": "Great! What stage is the Acme deal at?",
  "user_id": "user_123",
  "project_id": "deal_acme"
}

​
Chat Stream

POST /chat/stream
Stream a response via Server-Sent Events. Request: 
{
  "user_id": "user_123",
  "message": "Tell me about pipeline stages"
}
Response (SSE): 
data: Great
data: question
data: !
data: [DONE]

​
Get State

GET /state/{user_id}
GET /state/{user_id}?project_id=deal_acme
Retrieve cognitive state for a user. Response: 
{
  "user_id": "user_123",
  "user_mind": {
    "user_id": "user_123",
    "identity_type": "hunter",
    "patterns": {"follow_up_frequency": "high"},
    "total_interactions": 15,
    "trust_score": 0.72
  },
  "project_mind": {
    "project_id": "deal_acme",
    "journey_stage": "negotiating",
    "momentum_score": 0.85,
    "interaction_count": 8
  }
}

​
Explain State

GET /explain/{user_id}
GET /explain/{user_id}?project_id=deal_acme
Get a human-readable summary. Response: 
{
  "user_id": "user_123",
  "explanation": "User: user_123\nTotal interactions: 15\nTrust score: 0.72\nIdentity type: hunter\n\nProject: deal_acme\nJourney stage: negotiating\nInteractions: 8\nMomentum: 0.85"
}

​
Get Nudges

GET /nudges/{user_id}
Get pending nudges for a user. Response: 
[
  {
    "id": "nudge_abc123",
    "nudge_type": "stalled_deal",
    "title": "Deal going cold?",
    "message": "No activity on deal_acme in 8 days. Time to re-engage?",
    "priority": 7,
    "status": "pending"
  }
]

​
Generate Nudges

POST /nudges/{user_id}/generate
POST /nudges/{user_id}/generate?project_id=deal_acme
Generate new nudges based on current state. Response: 
[
  {
    "id": "nudge_xyz789",
    "nudge_type": "momentum_drop",
    "title": "Momentum slipping",
    "message": "Activity on deal_acme has dropped. What's blocking?",
    "priority": 8,
    "status": "pending"
  }
]

​
Dismiss Nudge

POST /nudges/{nudge_id}/dismiss
Mark a nudge as dismissed. Response: 
{
  "status": "dismissed",
  "nudge_id": "nudge_abc123"
}

​
Act on Nudge

POST /nudges/{nudge_id}/act
Mark a nudge as acted upon. Response: 
{
  "status": "acted",
  "nudge_id": "nudge_abc123"
}

​
Programmatic Usage

Create a custom FastAPI app: 
from fastapi import FastAPI
from sxth_mind.api import create_app
from sxth_mind.storage import SQLiteStorage
from examples.sales import SalesAdapter

# Create the sxth-mind app
sxth_app = create_app(
    adapter=SalesAdapter(),
    storage=SQLiteStorage("mind.db"),
    cors_origins=["http://localhost:3000"],
)

# Mount it in your app
app = FastAPI()
app.mount("/mind", sxth_app)

# Now available at /mind/chat, /mind/state/{user_id}, etc.

​
Security Note

The HTTP API has no built-in authentication. For production:
  1. Mount into your own app with your auth middleware
  2. Use a reverse proxy with authentication
  3. Deploy in a private network
See SECURITY.md for details.