Web API Reference

ContextFS provides a REST API through the web server for programmatic access to memories and sessions.

OpenAPI Specification

The server provides auto-generated OpenAPI documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

Starting the Server

# Start web server on default port (8000)
contextfs web

# Custom host and port
contextfs web --host 0.0.0.0 --port 8765

The server provides: - REST API at /api/* - Web UI at / - WebSocket at /ws for real-time updates - OpenAPI docs at /docs (Swagger UI) and /redoc (ReDoc)

Memory Endpoints

List Memories

GET /api/memories?limit=20&type=fact&namespace=repo-name

Parameter	Type	Description
limit	int	Max results (1-100, default: 20)
type	string	Filter by memory type
namespace	string	Filter by namespace

Response:

{
  "success": true,
  "data": [
    {
      "id": "abc123...",
      "content": "Memory content",
      "type": "fact",
      "tags": ["tag1", "tag2"],
      "summary": "Brief summary",
      "namespace_id": "repo-name",
      "project": "project-name",
      "created_at": "2024-01-15T10:30:00",
      "updated_at": "2024-01-15T10:30:00"
    }
  ]
}

Get Memory

GET /api/memories/{memory_id}

Supports partial ID matching (8+ characters).

Create Memory

POST /api/memories
Content-Type: application/json

{
  "content": "Memory content",
  "type": "decision",
  "tags": ["api", "design"],
  "summary": "API design decision"
}

Update Memory

PUT /api/memories/{memory_id}
Content-Type: application/json

{
  "content": "Updated content",
  "type": "fact",
  "tags": ["updated", "tags"],
  "summary": "Updated summary",
  "project": "my-project"
}

All fields are optional - only provided fields will be updated.

Delete Memory

DELETE /api/memories/{memory_id}

Search Endpoint

Search Memories

GET /api/search?q=query&type=fact&semantic=true&limit=20

Parameter	Type	Description
q	string	Search query (required)
type	string	Filter by memory type
namespace	string	Filter by namespace
limit	int	Max results (1-100, default: 20)
offset	int	Pagination offset
semantic	bool	Use semantic search (default: true)
smart	bool	Use smart routing based on memory type

Response:

{
  "success": true,
  "data": [
    {
      "memory": { ... },
      "score": 0.95,
      "highlights": ["matched <mark>text</mark>"],
      "source": "rag"
    }
  ]
}

Dual Search

GET /api/search/dual?q=query

Returns results from both FTS and RAG backends separately.

Session Endpoints

List Sessions

GET /api/sessions?limit=20&offset=0&tool=claude-code

Parameter	Type	Description
limit	int	Max results (1-100, default: 20)
offset	int	Pagination offset
tool	string	Filter by tool name

Get Session

GET /api/sessions/{session_id}

Returns session details including all messages.

Update Session

PUT /api/sessions/{session_id}
Content-Type: application/json

{
  "label": "new-label",
  "summary": "Session summary"
}

Delete Session

DELETE /api/sessions/{session_id}

Deletes the session and all associated messages.

Utility Endpoints

Get Statistics

GET /api/stats

Response:

{
  "success": true,
  "data": {
    "total_memories": 150,
    "memories_by_type": {
      "fact": 50,
      "decision": 30,
      "procedural": 40,
      "code": 30
    },
    "total_sessions": 25,
    "namespaces": ["repo1", "repo2"],
    "fts_indexed": 150,
    "rag_indexed": 150
  }
}

Get Namespaces

GET /api/namespaces

Export Memories

GET /api/export

Downloads all memories as JSON file.

Download Database

GET /api/database

Downloads SQLite database for offline use with sql.js.

WebSocket

Connect to /ws for real-time updates:

const ws = new WebSocket('ws://localhost:8000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'memory_created':
      console.log('New memory:', data.memory);
      break;
    case 'memory_updated':
      console.log('Updated memory:', data.memory);
      break;
    case 'memory_deleted':
      console.log('Deleted memory:', data.id);
      break;
    case 'session_updated':
      console.log('Updated session:', data.session);
      break;
    case 'session_deleted':
      console.log('Deleted session:', data.id);
      break;
  }
};

// Keep alive
ws.send(JSON.stringify({ type: 'ping' }));

Error Handling

All endpoints return consistent error responses:

{
  "success": false,
  "error": "Error message"
}

HTTP status codes: - 200 - Success - 404 - Resource not found - 422 - Validation error - 500 - Server error