{"openapi":"3.1.0","info":{"title":"memory HTTP API","description":"Global searchable memory for LLMs (MongoDB Atlas + Cloudflare R2). Machine clients use `Authorization: Bearer mem_tok_…` issued in the admin UI. Human-friendly guide: `GET /api/guide`. LLM skill install prompt: `GET /api/skill-prompt`.","version":"1.0.0"},"paths":{"/api/health":{"get":{"tags":["meta"],"summary":"Health","description":"Lightweight liveness probe used by the launcher's wait-for-ready loop.","operationId":"health_api_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Api Health Get"}}}}}}},"/api/guide":{"get":{"tags":["meta"],"summary":"Api Guide","description":"Open API guide: auth, scopes, endpoints, request/response examples.\n\nPublic (no auth). Prefer this for LLM tooling; OpenAPI is also at\n``/openapi.json`` and Swagger UI at ``/docs``.","operationId":"api_guide_api_guide_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Guide Api Guide Get"}}}}}}},"/api/skill-prompt":{"get":{"tags":["meta"],"summary":"Skill Prompt","description":"Paste-ready prompt that teaches an LLM to use this host as memory.\n\nQuery:\n  - ``format=json`` (default) → ``{ok, prompt, base_url, ...}``\n  - ``format=text`` or ``markdown`` → raw markdown body\n  - ``token_env`` → env var name referenced in the prompt","operationId":"skill_prompt_api_skill_prompt_get","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"json","title":"Format"}},{"name":"token_env","in":"query","required":false,"schema":{"type":"string","default":"MEMORY_API_TOKEN","title":"Token Env"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Skill Prompt Api Skill Prompt Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/login":{"post":{"summary":"Login","description":"Verify admin credentials and set the session cookie.","operationId":"login_api_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Login Api Login Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/logout":{"post":{"summary":"Logout","description":"Clear the session cookie.","operationId":"logout_api_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Logout Api Logout Post"}}}}}}},"/api/me":{"get":{"summary":"Me","description":"Report auth state so the frontend can show/hide the login screen.","operationId":"me_api_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Me Api Me Get"}}}}}}},"/api/schema":{"get":{"summary":"Schema","description":"Static form definition so the frontend renders fields dynamically.","operationId":"schema_api_schema_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Schema Api Schema Get"}}}}}}},"/api/config":{"get":{"summary":"Get Config","description":"Resolved config (secrets masked) + a one-line backend-status summary.","operationId":"get_config_api_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Config Api Config Get"}}}}}},"post":{"summary":"Save Config","description":"Save the submitted fields (creds → creds.db, settings → config.toml).\n\nPartial saves are allowed so Mongo can be filled and tested before R2\n(and vice versa). ``complete`` / ``missing`` in the response reflect\noverall readiness; they do not block the write.","operationId":"save_config_api_config_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveConfigBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Save Config Api Config Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/config/raw":{"get":{"summary":"Get Raw Config","description":"Unmasked current values for populating the edit form.\n\nServed on a separate endpoint from the masked view so the form can\nprefill real secrets while the read-only Config tab stays masked.","operationId":"get_raw_config_api_config_raw_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Raw Config Api Config Raw Get"}}}}}}},"/api/config/path":{"get":{"summary":"Config Path Info","description":"Config file + credential-store paths and whether they exist.","operationId":"config_path_info_api_config_path_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Config Path Info Api Config Path Get"}}}}}}},"/api/tokens":{"get":{"summary":"List Tokens","description":"List API tokens (metadata only — no secrets).","operationId":"list_tokens_api_tokens_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Tokens Api Tokens Get"}}}}}},"post":{"summary":"Create Token","description":"Create a token. Plaintext secret is returned once.","operationId":"create_token_api_tokens_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTokenBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Create Token Api Tokens Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/tokens/{token_id}":{"patch":{"summary":"Update Token","description":"Update token metadata (name, scopes, expiry, IPs). Does not rotate secret.","operationId":"update_token_api_tokens__token_id__patch","parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTokenBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Token Api Tokens  Token Id  Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Token","operationId":"delete_token_api_tokens__token_id__delete","parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Token Api Tokens  Token Id  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/tokens/{token_id}/revoke":{"post":{"summary":"Revoke Token","operationId":"revoke_token_api_tokens__token_id__revoke_post","parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string","title":"Token Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Revoke Token Api Tokens  Token Id  Revoke Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/test":{"post":{"summary":"Test Connections","description":"Test one backend ('mongo' / 'r2') or 'all'. Returns per-backend results.","operationId":"test_connections_api_test_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Test Connections Api Test Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/memories":{"get":{"tags":["memories"],"summary":"List or search memories","description":"Search (when ``q`` is non-empty) or list memories with filters.\n\nPagination: ``page``+``limit``, or ``skip``, or cursor ``after`` (list only).","operationId":"list_memories_api_memories_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"Full-text search; empty = recent list","default":"","title":"Q"},"description":"Full-text search; empty = recent list"},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by type","title":"Type"},"description":"Filter by type"},{"name":"scope","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by scope","title":"Scope"},"description":"Filter by scope"},{"name":"agent","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by agent name","title":"Agent"},"description":"Filter by agent name"},{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Only memories from last N days","title":"Days"},"description":"Only memories from last N days"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO datetime lower bound","title":"Since"},"description":"ISO datetime lower bound"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"Page size 1–200","default":20,"title":"Limit"},"description":"Page size 1–200"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"1-based page (offset mode)","default":1,"title":"Page"},"description":"1-based page (offset mode)"},{"name":"skip","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Absolute offset","title":"Skip"},"description":"Absolute offset"},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor from previous page (list mode; preferred for large sets)","title":"After"},"description":"Cursor from previous page (list mode; preferred for large sets)"}],"responses":{"200":{"description":"Paginated memory previews","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Memories Api Memories Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]},"post":{"tags":["memories"],"summary":"Store a memory","description":"Store a new memory (R2 content + Mongo index).\n\nExample body::\n\n    {\"title\":\"Use JWT\",\"type\":\"decision\",\"tags\":[\"auth\"],\"content\":\"RS256…\"}","operationId":"store_memory_api_memories_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreMemoryBody"}}}},"responses":{"200":{"description":"Created memory document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Store Memory Api Memories Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/memories/{memory_id}":{"patch":{"tags":["memories"],"summary":"Update a memory","description":"Update fields on an existing memory (only provided fields change).","operationId":"update_memory_api_memories__memory_id__patch","parameters":[{"name":"memory_id","in":"path","required":true,"schema":{"type":"string","title":"Memory Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMemoryBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Memory Api Memories  Memory Id  Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]},"get":{"tags":["memories"],"summary":"Get Memory","description":"Fetch a single memory (metadata + R2 content).","operationId":"get_memory_api_memories__memory_id__get","parameters":[{"name":"memory_id","in":"path","required":true,"schema":{"type":"string","title":"Memory Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Memory Api Memories  Memory Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]},"delete":{"tags":["memories"],"summary":"Delete Memory","description":"Delete a memory from MongoDB + R2.","operationId":"delete_memory_api_memories__memory_id__delete","parameters":[{"name":"memory_id","in":"path","required":true,"schema":{"type":"string","title":"Memory Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Memory Api Memories  Memory Id  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/memories/bulk-delete":{"post":{"tags":["memories"],"summary":"Bulk delete","description":"Delete many memories by id. Requires ``memory:delete``.","operationId":"bulk_delete_api_memories_bulk_delete_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Bulk Delete Api Memories Bulk Delete Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/stats":{"get":{"tags":["memories"],"summary":"Stats","description":"Aggregate counts by type / scope / project for the dashboard.","operationId":"stats_api_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Stats Api Stats Get"}}}}},"security":[{"BearerAuth":[]}]}},"/api/status":{"get":{"tags":["meta"],"summary":"Backend health strip (Mongo, R2, public URL)","description":"Lightweight status for the dashboard (admin or any authenticated client).","operationId":"system_status_api_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response System Status Api Status Get"}}}}}}},"/api/memories/{memory_id}/download":{"get":{"tags":["memories"],"summary":"Download .md or presigned URL","description":"Download full markdown from R2, or a time-limited presigned URL.","operationId":"download_memory_api_memories__memory_id__download_get","parameters":[{"name":"memory_id","in":"path","required":true,"schema":{"type":"string","title":"Memory Id"}},{"name":"url","in":"query","required":false,"schema":{"type":"boolean","description":"If true, return a presigned GET URL","default":false,"title":"Url"},"description":"If true, return a presigned GET URL"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Download Memory Api Memories  Memory Id  Download Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerAuth":[]}]}},"/api/skill-pack.zip":{"get":{"tags":["meta"],"summary":"Download skill pack zip","description":"ZIP with SKILL.md + .env.example for installing remote-memory in an LLM tool.","operationId":"skill_pack_zip_api_skill_pack_zip_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/derive-endpoint":{"post":{"summary":"Derive","description":"Resolve an R2 endpoint from account id + explicit endpoint.\n\nLets the form show a live 'Resolved endpoint' hint without duplicating\nthe derivation logic in JS.","operationId":"derive_api_derive_endpoint_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Derive Api Derive Endpoint Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"summary":"Index","operationId":"index__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"BulkDeleteBody":{"properties":{"ids":{"items":{"type":"string"},"type":"array","title":"Ids","default":[]}},"type":"object","title":"BulkDeleteBody"},"CreateTokenBody":{"properties":{"name":{"type":"string","title":"Name","default":""},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"preset":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preset"},"expires_in_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires In Days"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At"},"allowed_ips":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Ips"}},"type":"object","title":"CreateTokenBody"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LoginBody":{"properties":{"username":{"type":"string","title":"Username","default":""},"password":{"type":"string","title":"Password","default":""}},"type":"object","title":"LoginBody"},"SaveConfigBody":{"properties":{"mongodb_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mongodb Uri"},"mongodb_db":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mongodb Db"},"memory_collection":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Memory Collection"},"r2_account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"R2 Account Id"},"r2_access_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"R2 Access Key Id"},"r2_secret_access_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"R2 Secret Access Key"},"r2_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"R2 Bucket"},"r2_endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"R2 Endpoint"},"r2_public_base":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"R2 Public Base"},"r2_presign_ttl":{"anyOf":[{},{"type":"null"}],"title":"R2 Presign Ttl"}},"type":"object","title":"SaveConfigBody"},"StoreMemoryBody":{"properties":{"content":{"type":"string","title":"Content","default":""},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent"},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project"}},"type":"object","title":"StoreMemoryBody"},"TestBody":{"properties":{"target":{"type":"string","title":"Target","default":"all"}},"type":"object","title":"TestBody"},"UpdateMemoryBody":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent"},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project"}},"type":"object","title":"UpdateMemoryBody"},"UpdateTokenBody":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At"},"clear_expiry":{"type":"boolean","title":"Clear Expiry","default":false},"allowed_ips":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Ips"},"unrevoke":{"type":"boolean","title":"Unrevoke","default":false}},"type":"object","title":"UpdateTokenBody"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mem_tok_…","description":"API token from admin UI → API Tokens. Scopes: memory:read, memory:write, memory:delete."}}},"externalDocs":{"description":"JSON API guide (auth, request/response examples)","url":"/api/guide"}}