+
+
+
+
SpiralSafe API Reference
+
+ Interactive documentation for the SpiralSafe coherence engine API.
+ Test endpoints directly from your browser.
+
+
+
+
+
+ Base URL:
+ https://api.spiralsafe.org
+
+
+ Version:
+ v1.0
+
+
+ Auth:
+ X-API-Key header
+
+
+
+
+
+
+ 🔐 Authentication
+
+ All API endpoints require authentication via the X-API-Key header.
+
+ curl -X GET https://api.spiralsafe.org/api/health \
+ -H "X-API-Key: your-api-key"
+
+
Getting an API Key:
+
Contact the SpiralSafe team or use the Admin Console to manage your API keys.
+
+
+
+
+
+
+ GET
+ /api/health
+
+ Check the health status of the SpiralSafe API.
+
+
+
+
+
+ Example Response
+ {
+ "status": "healthy",
+ "timestamp": "2026-01-22T07:05:40.266Z",
+ "services": {
+ "wave": "operational",
+ "bump": "operational",
+ "awi": "operational",
+ "atom": "operational",
+ "sphinx": "operational"
+ }
+}
+
+
+
+
+
+
+ POST
+ /api/wave/analyze
+
+ Analyze content for coherence using the WAVE protocol. Detects curl (repetition), divergence, and potential.
+
+ Request Body:
+ {
+ "content": "Your text content to analyze for coherence...",
+ "context": {
+ "type": "conversation",
+ "participants": ["claude", "human"]
+ }
+}
+
+
+ Example Response
+ {
+ "curl": 0.15,
+ "divergence": 0.08,
+ "potential": 0.72,
+ "regions": [
+ {
+ "start": 0,
+ "end": 150,
+ "type": "high_potential",
+ "severity": "warning",
+ "description": "Unrealized concept cluster detected"
+ }
+ ],
+ "coherent": true
+}
+
+
+
+
+
🧪 Try It
+
+
+
+
+
+
+
+
+
+ POST
+ /api/bump/create
+
+ Create a handoff marker between agents or systems using the H&&S:BUMP protocol.
+
+ Request Body:
+ {
+ "type": "WAVE",
+ "from": "claude",
+ "to": "copilot",
+ "state": "architecture_review_complete",
+ "context": {
+ "pr_number": 123,
+ "files_changed": ["src/api.ts", "tests/api.test.ts"]
+ }
+}
+
+ Bump Types:
+
+
WAVE - Soft handoff
+
PASS - Full transfer
+
PING - Status update
+
SYNC - Synchronize
+
BLOCK - Blocker
+
+
+
+ Example Response
+ {
+ "id": "bump-uuid-12345",
+ "type": "WAVE",
+ "from": "claude",
+ "to": "copilot",
+ "state": "architecture_review_complete",
+ "context": { ... },
+ "timestamp": "2026-01-22T07:05:40.266Z",
+ "resolved": false
+}
+
+
+
+
+
+
+ POST
+ /api/bump/query
+
+ Query existing bump markers with filters.
+
+ Request Body:
+ {
+ "from": "claude",
+ "type": "WAVE",
+ "resolved": false,
+ "limit": 10
+}
+
+
+
+
+
+ POST
+ /api/awi/request
+
+ Request authorization for an action using the AWI (Authorization-With-Intent) protocol.
+
+ Request Body:
+ {
+ "intent": "deploy_to_production",
+ "scope": {
+ "resources": ["api.spiralsafe.org"],
+ "actions": ["deploy"],
+ "time_limit": "1h"
+ },
+ "level": 2
+}
+
+ AWI Levels:
+
+
Level 0: Information gathering only
+
Level 1: Reversible actions (can be undone)
+
Level 2: Significant changes (require review)
+
Level 3: Critical actions (production impact)
+
Level 4: Irreversible changes (data deletion)
+
+
+
+
+
+
+ POST
+ /api/awi/verify
+
+ Verify if an AWI grant is still valid and within scope.
+
+ Request Body:
+ {
+ "grant_id": "awi-grant-uuid",
+ "action": "deploy",
+ "resource": "api.spiralsafe.org"
+}
+
+
+
+
+
+ POST
+ /api/atom/trail/log
+
+ Log a decision to the ATOM (Auditable Trail of Metadata) persistence layer.
+
+ Request Body:
+ {
+ "actor": "claude",
+ "decision": "Design architecture for authentication system",
+ "rationale": "Initial planning phase requires clear structure",
+ "outcome": "COMPLETE",
+ "coherenceScore": 0.85,
+ "context": {
+ "feature": "user-authentication",
+ "phase": "planning"
+ },
+ "parentEntry": "uuid-of-previous-decision"
+}
+
+
+ Example Response
+ {
+ "id": "atom-uuid-67890",
+ "success": true
+}
+
+
+
+
+
+
+ POST
+ /api/atom/trail/query
+
+ Query the ATOM trail with filters.
+
+ Request Body:
+ {
+ "actor": "claude",
+ "since": "2026-01-19T00:00:00Z",
+ "outcome": "COMPLETE",
+ "minCoherence": 0.7,
+ "limit": 50
+}
+
+
+
+
+
+ GET
+ /api/atom/trail/verify
+
+ Verify the integrity of the entire ATOM trail (detect tampering).
+
+
+ Example Response
+ {
+ "valid": true,
+ "totalEntries": 150,
+ "brokenChains": 0,
+ "tamperedEntries": [],
+ "details": []
+}
+
+
+
+
+
+
+ POST
+ /api/sphinx/gate
+
+ Validate passage through a SPHINX security gate. The guardian asks its riddles.
+
+ Request Body:
+ {
+ "gate": "COHERENCE",
+ "artifact": {
+ "type": "document",
+ "content": "Content to validate..."
+ },
+ "options": {
+ "threshold": 0.6,
+ "strict": false
+ }
+}
+
+ SPHINX Gates:
+
+
ORIGIN: "Where do you come from?" - Verify genesis lineage
+
INTENT: "What do you seek?" - Verify stated purpose
+
COHERENCE: "Are you whole?" - Verify >60% threshold
+
IDENTITY: "Who are you?" - Verify agent/user auth
+
PASSAGE: "You may pass." - Grant transition
+
+
+
+ Example Response
+ {
+ "gate": "COHERENCE",
+ "passed": true,
+ "score": 0.72,
+ "threshold": 0.6,
+ "verdict": "PASSAGE",
+ "message": "Coherence verified. You may pass."
+}
+
+
+
+
+
+ ⚡ Rate Limits
+
+
+ Default requests
+ 100 / 60 seconds
+
+
+ Auth failures
+ 5 / 60 seconds
+
+
+ Wave analysis
+ 20 / 60 seconds
+
+
+
+
+
+
+ 📚 API Documentation Alternatives
+
+ This documentation is inspired by modern API documentation tools. Here are some excellent alternatives:
+
+
+
+
+
+
+
+
+
+