Sibyl API Reference

Sibyl provides a dual-interface API: a thirteen-tool MCP interface for assistant clients and automation, plus a full REST API for applications and integrations. Both surfaces are served by the same daemon (sibyld) and share one SurrealDB-native runtime for graph, content, and auth.

Architecture Overview

Sibyl Combined App (Starlette, port 3334)
|-- /api/*    --> FastAPI REST endpoints (31 routers)
|-- /mcp      --> MCP streamable-http transport (13 tools, 2 resources)
|-- /ws       --> WebSocket for real-time updates
'-- Lifespan  --> Coordination runtime + session management

The coordination runtime is in-process by default. Set SIBYL_COORDINATION_BACKEND=redis for multi-process or distributed worker deployments.

Base URL

Environment	Base URL
Local Development	http://localhost:3334
Production	https://api.your-domain.com

API Interfaces

MCP Tools (for Assistant Clients)

The MCP interface exposes thirteen tools that cover discovery, context, bounded traversal, capture, synthesis, lifecycle operations, and introspection. Tools are registered in apps/api/src/sibyl/server.py.

Tool	Purpose	Documentation
search	Semantic search across knowledge graph and documents	mcp-search.md
context	Compile a structured context pack for an agent goal	mcp-context.md
synthesis_plan	Plan a source-grounded synthesis outline	mcp-synthesis.md
synthesis_draft	Draft, verify, and optionally remember a synthesis artifact	mcp-synthesis.md
synthesis_verify	Verify citation, freshness, hidden-context, and gap coverage	mcp-synthesis.md
explore	Navigate and browse graph structure	mcp-explore.md
expand_neighbors	Widen known memories into their bounded graph neighborhood	mcp-traverse.md
fetch_slice	Read one memory at span granularity, with parent citation	mcp-traverse.md
add	Create new knowledge entities	mcp-add.md
remember	Capture durable memory with verbatim raw provenance	mcp-remember.md
reflect	Reflect raw notes into reviewable memory candidates	mcp-reflect.md
manage	Task, epic, source, and analysis lifecycle operations	mcp-manage.md
logs	Recent server logs (OWNER role)	mcp-logs.md

MCP Endpoint: POST /mcp (streamable-http transport)

The MCP server also exposes two resources: sibyl://health (connectivity and entity counts) and sibyl://stats (knowledge graph statistics).

REST API (for Applications)

The REST API spans 31 routers. The pages below cover the most commonly used surfaces; the full contract is in the OpenAPI schema.

Category	Endpoints	Documentation
Entities	/api/entities/*	rest-entities.md
Tasks	/api/tasks/*	rest-tasks.md
Projects	/api/entities?entity_type=project	rest-projects.md
Search	/api/search, /api/search/explore, /api/search/expand, /api/search/slice	rest-search.md
Memory	/api/memory/*, /api/context/*	rest-memory.md
Synthesis	/api/synthesis/*	rest-synthesis.md

Additional routers not covered by dedicated pages include auth, users, epics, experience, graph, crawler, ingestion, rag, resolve, jobs, backups, settings, ai_settings, metrics, telemetry, admin, logs, orgs, org_members, org_invitations, invitations, project_members, session, setup, and teams. All are described in the OpenAPI schema.

A few prefixes are worth calling out because they do not match the router name. The crawler router is mounted under /sources (for example /api/sources/...), not /crawler. The org_invitations router serves org-scoped invitations under /api/orgs/{slug}/invitations, while the separate invitations router serves invitation acceptance under /api/invitations. The ingestion router (prefix /ingestion) backs the sibyl ingest CLI with paths under /api/ingestion/imports, /api/ingestion/documents, and /api/ingestion/collections. The experience router is mounted under /memory and serves POST /api/memory/experience (see rest-memory.md). The teams router serves team management under /api/teams (see auth-authorization.md).

OpenAPI Spec: Available at /api/docs (Swagger UI) and /api/openapi.json

Authentication & Authorization

Sibyl supports multiple authentication methods and role-based access control:

Topic	Description	Documentation
JWT Sessions	Web clients, browser-based apps	auth-jwt.md
API Keys	Programmatic access, CI/CD	auth-api-keys.md
OAuth (GitHub)	Social login	auth-jwt.md
OIDC / SSO	Corporate identity providers	auth-jwt.md
Authorization	Roles, permissions, RLS	auth-authorization.md

Quick Start

For REST API:

# Using JWT token (from login)
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  http://localhost:3334/api/entities

# Using API key
curl -H "Authorization: Bearer sk_live_abc123..." \
  http://localhost:3334/api/entities

For MCP:

# API key with mcp scope
curl -X POST http://localhost:3334/mcp \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {"name": "search", "arguments": {"query": "OAuth patterns"}}}'

Multi-Tenancy

Sibyl is multi-tenant by design, with separate isolation models for graph memory and shared runtime tables. Each organization gets a dedicated graph namespace (org_<uuid_hex>). Content and auth records live in shared SurrealDB namespaces and are scoped by organization_id, table permissions, and the API policy layer.

• Isolated SurrealDB graph namespace per organization
• Org-scoped content and auth records in shared namespaces
• Scoped API and MCP access

Organization Context:

• JWT tokens include org claim with organization ID
• API keys are scoped to specific organizations
• Graph queries route to the resolved organization namespace
• Content and auth queries carry explicit organization predicates

Rate Limiting

REST endpoints are rate-limited using SlowAPI:

Tier	Limit
Default	100 requests/minute
Search	30 requests/minute
Auth	5 requests/minute
Crawl	10 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

WebSocket Events

Real-time updates are available via WebSocket at /ws:

// Browser clients authenticate with the existing sibyl_access_token cookie.
const ws = new WebSocket("ws://localhost:3334/ws");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Event types: entity_created, entity_updated, entity_deleted,
  // crawl_started, crawl_progress, crawl_complete, etc.
};

Error Responses

All errors follow a consistent envelope. A global exception handler returns a structured JSON body and echoes the correlation ID in an X-Request-ID response header:

{
  "error": "not_found",
  "message": "The requested resource was not found.",
  "request_id": "req_a1b2c3d4e5f6",
  "remediation": "Check the ID or prefix and try again.",
  "details": {
    "field": "task_id"
  }
}

The error field is a stable machine-readable code (for example authentication_required, forbidden, not_found, conflict, validation_error, rate_limited, internal_error). remediation is a short hint for resolving the error, and details is optional and only present when the handler has safe, structured context to share.

Status Code	Meaning
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid credentials
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Resource locked or concurrent update
422	Validation Error - Request body validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Configuration

Required Environment Variables

SIBYL_OPENAI_API_KEY=sk-...       # For embeddings
SIBYL_JWT_SECRET=...              # For authentication

Optional Configuration

SIBYL_LOG_LEVEL=INFO
SIBYL_EMBEDDING_MODEL=text-embedding-3-small
SIBYL_MCP_AUTH_MODE=auto  # auto, on, or off

Next Steps

• MCP Search Tool - Start with semantic search
• MCP Context Tool - Compile context packs for agents
• MCP Synthesis Tools - Source-grounded artifacts
• REST Entities API - CRUD operations
• JWT Authentication - Set up authentication
• Authorization - Roles, scopes, and isolation