{"openapi":"3.1.0","info":{"title":"Recall Racoon API","version":"2.4.0","description":"MCP-native persistent memory API for AI agents. Hybrid search, governed lifecycle, secret redaction.","contact":{"name":"Recall Racoon","email":"api@recallracoon.com","url":"https://www.recallracoon.com"},"license":{"name":"Proprietary","url":"https://www.recallracoon.com/terms"}},"servers":[{"url":"https://api.recallracoon.com/v1","description":"Production"},{"url":"https://staging-api.recallracoon.com/v1","description":"Staging"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/ingest":{"post":{"summary":"Ingest content for processing","operationId":"ingestContent","tags":["Ingestion"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRequest"}}}},"responses":{"202":{"description":"Accepted for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/search":{"post":{"summary":"Execute hybrid semantic search","operationId":"searchMemories","tags":["Search"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/memories/{id}":{"get":{"summary":"Retrieve a single memory with full provenance","operationId":"getMemory","tags":["Memories"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^MEM-\\d{3}$"}}],"responses":{"200":{"description":"Memory details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/memories/{id}/related":{"get":{"summary":"Get graph neighbors and relationships","operationId":"getRelatedMemories","tags":["Memories"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"depth","in":"query","schema":{"type":"integer","minimum":1,"maximum":3,"default":1}}],"responses":{"200":{"description":"Related memories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelatedMemoriesResponse"}}}}}}},"/steward/trigger":{"post":{"summary":"Manually trigger Rummage processing","operationId":"triggerSteward","tags":["Steward"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StewardTriggerRequest"}}}},"responses":{"202":{"description":"Processing triggered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StewardTriggerResponse"}}}}}}},"/audit":{"get":{"summary":"Query audit log with filters","operationId":"queryAuditLog","tags":["Admin"],"security":[{"ApiKeyAuth":[],"AdminRole":[]}],"parameters":[{"name":"namespace","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"actor","in":"query","schema":{"type":"string"}},{"name":"action","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Audit log entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditLogResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Namespace-scoped API key"},"AdminRole":{"type":"apiKey","in":"header","name":"X-Admin-Token","description":"Admin role token for privileged operations"}},"schemas":{"IngestRequest":{"type":"object","required":["content","namespace"],"properties":{"content":{"type":"string","description":"Raw content to ingest"},"namespace":{"type":"string","pattern":"^[a-z0-9-]{1,64}$"},"source":{"type":"string","description":"Source identifier (file, API, agent, etc.)"},"metadata":{"type":"object","additionalProperties":true},"citations":{"type":"array","items":{"type":"string"}},"options":{"type":"object","properties":{"skipRedaction":{"type":"boolean","default":false},"skipProbes":{"type":"boolean","default":false},"priority":{"type":"string","enum":["normal","high"],"default":"normal"}}}}},"IngestResponse":{"type":"object","properties":{"claimId":{"type":"string","pattern":"^MEM-\\d{3}$"},"status":{"type":"string","enum":["candidate","processing"]},"message":{"type":"string"}}},"SearchRequest":{"type":"object","required":["query","namespace"],"properties":{"query":{"type":"string","minLength":1,"maxLength":500},"namespace":{"type":"string"},"filters":{"type":"object","properties":{"status":{"type":"array","items":{"type":"string","enum":["confirmed","stale","superseded","archived"]}},"confidenceMin":{"type":"number","minimum":0,"maximum":1},"freshnessDays":{"type":"integer","minimum":1},"tags":{"type":"array","items":{"type":"string"}}}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100,"default":20},"cursor":{"type":"string"}}},"rrf":{"type":"object","properties":{"k":{"type":"integer","minimum":1,"maximum":100,"default":60}}}}},"SearchResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"total":{"type":"integer"},"cursor":{"type":"string","nullable":true},"tookMs":{"type":"integer"}}},"SearchResult":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"status":{"type":"string"},"confidence":{"type":"number"},"freshness":{"type":"string"},"source":{"type":"string"},"highlights":{"type":"array","items":{"type":"string"}},"citations":{"type":"array","items":{"type":"string"}}}},"MemoryDetail":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"status":{"type":"string","enum":["candidate","confirmed","stale","superseded","conflicted","archived"]},"confidence":{"type":"number"},"freshness":{"type":"string"},"source":{"type":"string"},"citations":{"type":"array","items":{"type":"string"}},"related":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RelatedMemoriesResponse":{"type":"object","properties":{"nodes":{"type":"array","items":{"$ref":"#/components/schemas/GraphNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/GraphEdge"}}}},"GraphNode":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"group":{"type":"string"},"status":{"type":"string"}}},"GraphEdge":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"type":{"type":"string","enum":["related","supersedes","contradicts","cites"]}}},"StewardTriggerRequest":{"type":"object","properties":{"namespace":{"type":"string"},"claimIds":{"type":"array","items":{"type":"string"}},"force":{"type":"boolean","default":false}}},"StewardTriggerResponse":{"type":"object","properties":{"taskId":{"type":"string"},"status":{"type":"string","enum":["queued","running"]},"message":{"type":"string"}}},"AuditLogResponse":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntry"}},"cursor":{"type":"string","nullable":true}}},"AuditEntry":{"type":"object","properties":{"id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"namespace":{"type":"string"},"actor":{"type":"string"},"action":{"type":"string"},"target":{"type":"string","nullable":true},"details":{"type":"object"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","nullable":true}}}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}}}}}