API Documentation

Quick Start

1. Get an API key (free, 10,000 credits)

curl -X POST https://api.sbs/api/sbs/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

2. Encode your first item

curl -X POST https://api.sbs/api/sbs/v3 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"action": "ingest", "text": "Distributed consensus via Raft"}'

3. Search for similar items

curl -X POST https://api.sbs/api/sbs/v3 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"action": "multi_search", "query": "fault tolerance"}'

Authentication

All API calls require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get a free API key at api.sbs/signup. Free tier includes 10,000 credits. L0 encoding is always free.

Base URL

https://api.sbs/api/sbs/v3

All endpoints use POST with a JSON body containing an action field.

Endpoints

POST

status

0 credits

Health check — returns vault item count and service status.

Request
{ "action": "status" }
Response
{ "service": "SBS v3", "items": 169, "levels": 5 }
POST

ingest

1 credit

Encode text into the spectral vault. Returns L0 binary and queues L1-L4 agents.

Request
{ "action": "ingest", "text": "Your content here", "sessionId": "optional-session-id" }
Response
{ "binary": "11000010011101011101000110001110", "credits_remaining": 9999 }
POST

search / multi_search

1 credit

Search the vault for spectrally similar items. Weighted across L0-L4.

Request
{ "action": "multi_search", "query": "distributed consensus", "topK": 5 }
Response
{ "results": [{ "text": "...", "distance": 0.12, "level": 3 }], "credits_remaining": 9998 }
POST

compare

1 credit

Head-to-head spectral comparison of two texts.

Request
{ "action": "compare", "textA": "First text", "textB": "Second text" }
Response
{ "hammingDistance": 8, "similarity": 0.75, "credits_remaining": 9997 }
POST

surface

4 credits

Deep auto-surface: finds contextually relevant items across all encoding levels.

Request
{ "action": "surface", "query": "legal indemnity clause", "topK": 10 }
Response
{ "surfaced": [{ "text": "...", "score": 0.94 }], "credits_remaining": 9993 }
POST

owl_lookup

0 credits

Deductive OWL lookup — queries Wikidata, ConceptNet, DBpedia. Free.

Request
{ "action": "owl_lookup", "query": "photosynthesis" }
Response
{ "wikidata": [...], "conceptnet": [...], "dbpedia": [...] }
POST

guide_respond

0 credits

AI-powered guide response using vault context. Used by SpectralGuide UI.

Request
{ "action": "guide_respond", "messages": [{"role":"user","text":"How does SBS work?"}], "context": {} }
Response
{ "response": "SBS uses DFT physics..." }

Encoding Levels

LevelNameMethodCost
L0SurfaceASCII DFT — deterministicFree
L1SemanticOWL IS/NOT decomposition1 AI call
L2ContextualDifferential vs session1 AI call
L3FoldKuramoto attractor clustering1 AI call
L4PortfolioCross-fold crystallisation1 AI call

TypeScript SDK

npm install @sbs/sdk
import { SBS } from '@sbs/sdk'

const sbs = new SBS({ apiKey: 'YOUR_API_KEY' })

// Encode
const result = await sbs.encode('Distributed consensus via Raft')
console.log(result.binary)  // "11001010..."

// Search
const matches = await sbs.search('fault tolerance', { topK: 5 })

// Compare
const diff = await sbs.compare('text A', 'text B')
console.log(diff.similarity)  // 0.75

SDK source available at packages/sbs-sdk/ in the repo. npm publish coming soon.

Credit Costs

ActionCreditsNotes
status0Always free
ingest1L0 instant, L1-L4 queued
search / multi_search1Weighted across levels
compare1Head-to-head
surface4Deep cross-level scan
owl_lookup0Deductive, runs on Vercel
guide_respond0AI guide (SpectralGuide)

Architecture

Developer / User
      │
      ▼
┌─────────────────┐
│ api.sbs (Vercel) │  Auth, credits, landing, SpectralGuide UI
│ Next.js          │  SDK target: POST /api/sbs/v3
└────────┬────────┘
         │ HTTP relay
         ▼
┌─────────────────┐
│ sbs-vault (Fly)  │  Float64 tensor + 12 encoding agents
│ Node.js          │  L0-L4 pipeline, OWL cascade, queue
│ Port 8080        │  Persistent volume /data
└────────┬────────┘
         │ HTTP client
         ▼
┌─────────────────┐
│ sbs-brain (Fly)  │  AI orchestrator (Z.ai MCP tools)
│ Python/FastAPI   │  Batch ops, benchmarking, auto-seeding
│ Port 8000        │
└─────────────────┘

API.SBS — Spectral Binary Search

HomeGet API KeyDashboardWorkspace