Skip to content

🌐 REST API Reference

Complete reference for all Spector REST endpoints. The API runs on an embedded Armeria server with virtual threads, accepting and returning JSON. Every request gets its own virtual thread — no connection limits to worry about.

  • Interactive API Playground

    Test live requests against your running Spector daemon (http://localhost:7070) and generate instant client snippets.

    Launch API Playground ↗

🔧 Base Configuration

Setting Default Description
Base URL http://localhost:7070 Configurable port
Content-Type application/json All requests and responses
Auth Header X-API-Key: <key> Optional, configured at startup
CORS Enabled All origins by default

Note

When an API key is configured, requests without a valid key receive 401 Unauthorized.

💚 System & Diagnostics

GET /api/v1/system/status

Quick status check returning system uptime, version, and configured Ollama details.

curl http://localhost:7070/api/v1/system/status

Response 200: 

{
  "status": "UP",
  "version": "1.0.0-SNAPSHOT",
  "uptime": "2h 15m 30s",
  "uptimeSeconds": 8130,
  "port": 7070,
  "ollamaUrl": "http://localhost:11434",
  "ollamaModel": "nomic-embed-text"
}

GET /api/v1/system/health

Detailed diagnostics of each subsystem component.

curl http://localhost:7070/api/v1/system/health

Response 200: 

{
  "status": "UP",
  "uptime": "PT2H15M30S",
  "timestamp": "2026-07-18T18:23:00Z",
  "components": {
    "memory": {
      "status": "UP",
      "engine": "SpectorMemory"
    },
    "llm": {
      "status": "CONFIGURED",
      "model": "llama3.2",
      "baseUrl": "http://localhost:11434"
    },
    "tools": {
      "status": "UP",
      "count": 16
    }
  }
}

GET /api/v1/system/metrics

Uptime, JVM heap stats, processors count, and Synapse configuration.

curl http://localhost:7070/api/v1/system/metrics

Response 200: 

{
  "jvm": {
    "version": "25",
    "vendor": "Oracle Corporation",
    "uptime": "PT2H15M30S",
    "heap": {
      "used": "142 MB",
      "max": "4096 MB",
      "total": "512 MB"
    },
    "processors": 8
  },
  "synapse": {
    "tools": 16,
    "memoryEngine": "active",
    "llmModel": "llama3.2"
  }
}

📥 Ingestion Endpoints

POST /api/v1/memory

Store a cognitive memory synchronously (standard store). Returns 201 Created with the assigned memory ID.

curl -X POST http://localhost:7070/api/v1/memory \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Spector hybrid search engine and cognitive memory",
    "tags": ["documentation", "architecture"],
    "importance": 0.85
  }'

🧠 Memory Endpoints

POST /api/v1/memory/remember

Store a cognitive memory asynchronously with tier, provenance, and affective hints. Returns 202 Accepted.

curl -X POST http://localhost:7070/api/v1/memory/remember \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pref-dark-mode",
    "text": "The user prefers dark mode for all editors",
    "tier": "SEMANTIC",
    "source": "USER_STATED",
    "tags": "ui,preferences",
    "interest": 0.9,
    "valence": 1
  }'

POST /api/v1/memory/recall

Cognitive recall with fused scoring across all memory tiers.

curl -X POST http://localhost:7070/api/v1/memory/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "dark theme settings", "topK": 5}'

DELETE /api/v1/memory/{id}

Tombstone (forget) a memory by ID. Logical deletion: the memory becomes invisible to recall, inspect, and export, but its payload content bytes remain on disk and in any backup or snapshot.

curl -X DELETE http://localhost:7070/api/v1/memory/pref-dark-mode

DELETE /api/v1/memory/{id}/purge

Physically destroy (purge) a memory by ID. Overwrites vector payload and content-derived headers with zeros in-place, detaches all graph association edges (Hebbian, temporal, entity, hyperedges), and logs the operation to the WAL. Irreversible.

Returns an audit report disclosing what was destroyed and copies that could not be reached (DR exports, replica disks, cold tier). Refuses with HTTP 409 (SPE-800-008) if the namespace is under active legal hold.

curl -X DELETE http://localhost:7070/api/v1/memory/pref-dark-mode/purge

POST /api/v1/memory/{id}/reinforce

Report positive or negative feedback for a memory via Long-Term Potentiation (LTP).

curl -X POST http://localhost:7070/api/v1/memory/pref-dark-mode/reinforce \
  -H "Content-Type: application/json" \
  -d '{"valence": 1}'

POST /api/v1/memory/{id}/suppress

Suppress or unsuppress a memory from recall consideration without deleting it.

curl -X POST http://localhost:7070/api/v1/memory/pref-dark-mode/suppress \
  -H "Content-Type: application/json" \
  -d '{"action": "suppress", "reason": "Deprecated configuration"}'

POST /api/v1/memory/{id}/resolve

Mark an active goal or tension as resolved (Zeigarnik closure).

curl -X POST http://localhost:7070/api/v1/memory/task-101/resolve \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}'

POST /api/v1/memory/introspect

Metamemory self-analysis — how well does the system know a topic?

curl -X POST http://localhost:7070/api/v1/memory/introspect \
  -H "Content-Type: application/json" \
  -d '{"topic": "kubernetes"}'

POST /api/v1/memory/reminder

Schedule a time-triggered reminder.

curl -X POST http://localhost:7070/api/v1/memory/reminder \
  -H "Content-Type: application/json" \
  -d '{"text": "Check build logs", "delaySeconds": 3600, "tags": "ci"}'

POST /api/v1/memory/scratchpad

Quick-write to working memory scratchpad.

POST /api/v1/memory/why-not

Explain why a memory was not recalled for a given query.

curl -X POST http://localhost:7070/api/v1/memory/why-not \
  -H "Content-Type: application/json" \
  -d '{"memoryId": "fact-42", "query": "pool config", "topK": 5}'

POST /api/v1/memory/reflect

Manually trigger a sleep consolidation cycle.

GET /api/v1/memory/status

Memory tier counts, partition info, and persistence status.

❌ Error Responses

Status Meaning
200 ✅ Success
400 Bad request (validation error, dimension mismatch)
401 Unauthorized (invalid or missing API key)
404 Resource not found
503 Service unavailable (embedding provider down)

🔗 See Also