API Reference

MemGhost exposes a RESTful API following OpenAPI 3.0 specifications. All API endpoints are versioned under /api/v1/.

API Services

The API is organized by domain module:

Service	Base Path	Description
Auth	/api/v1/auth	Authentication, login, token management
Vault	/api/v1/vault	Item capture, listing, classification
Notes	/api/v1/notes	Note CRUD, tags, folders, archive
Hubs	/api/v1/hubs	Hub graph, node content, quick-add
TTS	/api/v1/tts	Voice synthesis, voice management
Events	/api/v1/events	Server-Sent Events stream
Admin	/api/v1/admin	User, role, integration management

Common Patterns

Commands (Write Operations)

All write operations return 202 Accepted with a Location header:

POST /api/v1/vault/capture
Content-Type: application/json

{
  "content": "Meeting notes from standup",
  "source": "manual"
}

HTTP/1.1 202 Accepted
Location: /api/v1/vault/items/550e8400-e29b-41d4-a716-446655440000

Queries (Read Operations)

All read operations return 200 OK with the requested data:

GET /api/v1/notes/550e8400-e29b-41d4-a716-446655440000

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Meeting notes from standup",
  "type": "note",
  ...
}

Health Endpoints

GET /api/v1/health/live    # Liveness check (process is running)
GET /api/v1/health/ready   # Readiness check (database connected)

Authentication

Most endpoints require a Bearer token:

GET /api/v1/notes
Authorization: Bearer <jwt-token>

OpenAPI Specifications

API specs live in api/openapi/. Server code is generated via oapi-codegen with chi router bindings.