# Memory Gateway API curl examples This file keeps only the concrete API curl shapes and short notes. Replace `` with the key returned by `POST /users`. Base URL used in the live deployment test: ```text http://127.0.0.1:8010 ``` Test files: ```text tests/simple-multimodal-image.png tests/simple-tone.wav ``` ## 1. Health ```bash curl -sS http://127.0.0.1:8010/health ``` Expected shape: ```json { "status": "ok", "api": {"status": "ok"}, "backend": { "status": "ok", "base_url": "http://0.0.0.0:1995", "data": {"status": "ok"} } } ``` ## 2. Create user ```bash curl -sS -X POST http://127.0.0.1:8010/users \ -H 'Content-Type: application/json' \ -d '{"user_id":"gateway_demo_user"}' ``` Expected shape: ```json { "user_id": "gateway_demo_user", "user_key": "uk_REDACTED", "created_at": "2026-06-22T06:54:35.823262+00:00" } ``` Use the returned `user_key` in later requests. ## 3. Add chat memory with multipart files Use this when files belong to a chat/session message and the client should not or cannot convert the files to base64. `upload_id` rules: - `upload_id` is defined by the caller. - Gateway does not generate it. - Gateway does not require a format such as `user_id_filetype_number`. - It only needs to be non-empty, unique inside the request, and equal to the multipart file field name. - Good simple values are `image_1`, `image_2`, `audio_1`, `doc_1`. In the `messages` JSON, `upload_id: "image_1"` points to this file field: ```bash -F 'image_1=@tests/simple-multimodal-image.png;type=image/png' ``` Request: ```bash curl -sS -X POST http://127.0.0.1:8010/memories/add/multipart \ -F 'user_id=gateway_demo_user' \ -F 'user_key=' \ -F 'session_id=chat:gateway_demo_conversation' \ -F 'app_id=default' \ -F 'project_id=default' \ -F 'messages=[ { "sender_id": "gateway_demo_user", "role": "user", "timestamp": 1782111275810, "content": [ { "type": "text", "text": "请记住这次上传：图片里有左上红色方块、右上蓝色圆形、底部绿色横条；音频是一段短促测试音。" }, { "type": "image", "upload_id": "image_1", "name": "simple-multimodal-image.png", "ext": "png" }, { "type": "audio", "upload_id": "audio_1", "name": "simple-tone.wav", "ext": "wav" } ] } ]' \ -F 'image_1=@tests/simple-multimodal-image.png;type=image/png' \ -F 'audio_1=@tests/simple-tone.wav;type=audio/wav' ``` Expected shape: ```json { "session_id": "chat:gateway_demo_conversation", "backend": { "request_id": "0d6451f4077040e4af207cc6b034ea34", "data": { "message_count": 1, "status": "accumulated" } } } ``` Gateway stores the uploaded files and forwards upstream-compatible `base64` or `text` content. The client does not send `file://` and does not send base64. Common errors: - Missing file field for an `upload_id`: `422` - Duplicate `upload_id`: `422` - Extra uploaded file field not referenced by `messages`: `422` - Unsupported MIME type: `415` - File too large: `413` ## 4. Flush chat session `/memories/add/multipart` only appends messages. Call flush when the session should be extracted and indexed. ```bash curl -sS -X POST http://127.0.0.1:8010/memories/flush \ -H 'Content-Type: application/json' \ -d '{ "user_id": "gateway_demo_user", "user_key": "", "session_id": "chat:gateway_demo_conversation", "app_id": "default", "project_id": "default" }' ``` Expected shape: ```json { "session_id": "chat:gateway_demo_conversation", "backend": { "request_id": "4df5415115a34f109c564abd2f9012c6", "data": {"status": "extracted"} } } ``` ## 5. Search chat session ```bash curl -sS -X POST http://127.0.0.1:8010/memories/search \ -H 'Content-Type: application/json' \ -d '{ "user_id": "gateway_demo_user", "user_key": "", "conversation_id": "gateway_demo_conversation", "query": "图片里的蓝色圆形在哪里？底部是什么颜色的横条？", "scope": ["current_chat"], "top_k": 5, "app_id": "default", "project_id": "default" }' ``` Expected result excerpt: ```json { "results": [ { "session_id": "chat:gateway_demo_conversation", "source_scope": "current_chat", "text": "The image contained a red square, a blue circle, and a green horizontal rectangle.", "attachments": [ { "type": "image", "name": "simple-multimodal-image.png", "internal_uri": "file:///home/tom/memory-gateway/data/storage/..." }, { "type": "audio", "name": "simple-tone.wav", "internal_uri": "file:///home/tom/memory-gateway/data/storage/..." } ] } ] } ``` ## 6. Upload an independent resource Use `/resources` when the file is an independent resource, not just an attachment inside one chat message. ```bash curl -sS -X POST http://127.0.0.1:8010/resources \ -F 'user_id=gateway_demo_user' \ -F 'user_key=' \ -F 'app_id=default' \ -F 'project_id=default' \ -F 'title=Gateway demo image resource' \ -F 'description=Demo upload for simple multimodal image' \ -F 'file=@tests/simple-multimodal-image.png;type=image/png' ``` Expected shape: ```json { "resource_id": "r_1678eacf3e8c49f9a8863454c5b35e68", "session_id": "resource:gateway_demo_user:r_1678eacf3e8c49f9a8863454c5b35e68", "uri": "resource://gateway_demo_user/r_1678eacf3e8c49f9a8863454c5b35e68", "status": "extracted" } ``` Unlike `/memories/add/multipart`, `/resources` automatically calls upstream add and flush. ## 7. List resources ```bash curl -sS \ 'http://127.0.0.1:8010/resources?user_id=gateway_demo_user&user_key=' ``` Expected shape: ```json { "resources": [ { "resource_id": "r_1678eacf3e8c49f9a8863454c5b35e68", "filename": "simple-multimodal-image.png", "content_type": "image", "mime_type": "image/png", "uri": "resource://gateway_demo_user/r_1678eacf3e8c49f9a8863454c5b35e68", "session_id": "resource:gateway_demo_user:r_1678eacf3e8c49f9a8863454c5b35e68", "status": "extracted" } ] } ``` ## 8. Search resources ```bash curl -sS -X POST http://127.0.0.1:8010/memories/search \ -H 'Content-Type: application/json' \ -d '{ "user_id": "gateway_demo_user", "user_key": "", "query": "这张资源图片里有哪些几何图形和颜色？", "scope": ["resources"], "top_k": 5, "app_id": "default", "project_id": "default" }' ``` Expected result excerpt: ```json { "results": [ { "source_scope": "resources", "resource_id": "r_1678eacf3e8c49f9a8863454c5b35e68", "resource_uri": "resource://gateway_demo_user/r_1678eacf3e8c49f9a8863454c5b35e68", "text": "The image displayed a red square, a blue circle, and a green rectangle.", "attachments": [ { "type": "image", "name": "simple-multimodal-image.png", "internal_uri": "file:///home/tom/memory-gateway/data/storage/..." } ] } ] } ``` ## Multipart vs resources Use `/memories/add/multipart` when the upload belongs to a chat/session message: - caller supplies `session_id`, usually `chat:{conversation_id}`; - caller defines `upload_id` values in `messages`; - caller uploads files as form fields with names matching `upload_id`; - Gateway only calls upstream add; - caller should call `/memories/flush`; - search normally uses `current_chat` or `all_user_memory`. Use `/resources` when the upload is an independent resource: - Gateway creates `resource_id`; - Gateway creates `session_id = resource:{user_id}:{resource_id}`; - Gateway writes `user_resources`; - Gateway automatically calls upstream add and flush; - search normally uses `resources`.