REST

REST from cURL

The official SDKs are convenient, but they are not magic. They speak the same JSON the server expects, and you can drive that JSON from any shell. This page is a runnable tour of every method the SDKs expose, straight from curl.

Set the environment once

BASH

export API="https://api.memorysync.io"
export KEY="ms_live_..."
export END_USER="user_123"   # which of YOUR users this call is for

X-End-User-ID is required for API-key auth

Every example on this page passes X-End-User-ID: $END_USER. Omit it and the server returns HTTP 400 with code MISSING_END_USER_ID — the API will not infer it for you.

Headers every call carries

Header	Required	Notes
X-API-Key: $KEY	Yes	The only auth method documented for the SDKs.
Content-Type: application/json	On bodies	Always JSON.
Accept: application/json	Recommended	The server only returns JSON.
X-Project-ID: <id>	Optional	Scope to a project; same as the SDK option.
X-End-User-ID: <id>	Required for API-key auth	Identifies which of your end users the call belongs to. Server returns 400 MISSING_END_USER_ID without it.

Add a memory

BASH

curl -sS -X POST "$API/memory/add" \
  -H "X-API-Key: $KEY" \
  -H "X-End-User-ID: $END_USER" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The launch is on Friday.",
    "tags": ["plan"],
    "importance": 0.7
  }'

Bulk add (up to 50 items)

BASH

curl -sS -X POST "$API/memory/bulk-add" \
  -H "X-API-Key: $KEY" \
  -H "X-End-User-ID: $END_USER" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"text": "Decided on the schema."},
      {"text": "Wrote the migration."}
    ],
    "deduplicate": true
  }'

Query for recall

BASH

curl -sS -X POST "$API/memory/query" \
  -H "X-API-Key: $KEY" \
  -H "X-End-User-ID: $END_USER" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "when is launch",
    "k": 5,
    "filters": {"tags": ["plan"]}
  }'

Read / update / delete one memory

BASH

# fetch
curl -sS "$API/memory/42" \
  -H "X-API-Key: $KEY" -H "X-End-User-ID: $END_USER"

# update
curl -sS -X PATCH "$API/memory/42" \
  -H "X-API-Key: $KEY" -H "X-End-User-ID: $END_USER" \
  -H "Content-Type: application/json" \
  -d '{"importance": 0.95, "tags": ["important"]}'

# delete one or many
curl -sS -X DELETE "$API/memory/forget" \
  -H "X-API-Key: $KEY" -H "X-End-User-ID: $END_USER" \
  -H "Content-Type: application/json" \
  -d '{"memory_ids": [42, 43], "reason": "wrong"}'

Compose a prompt with retrieved memories

BASH

curl -sS -X POST "$API/memory/compose" \
  -H "X-API-Key: $KEY" -H "X-End-User-ID: $END_USER" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_template": "Prior context: {{memories}}\nQuestion: {{query}}",
    "recall_k": 5,
    "max_tokens": 800
  }'

Export, summarize, relate

BASH

# everything you can read
curl -sS "$API/memory/export" \
  -H "X-API-Key: $KEY" -H "X-End-User-ID: $END_USER"

# collapse a list of memories into a summary memory
curl -sS -X POST "$API/memory/summarize" \
  -H "X-API-Key: $KEY" -H "X-End-User-ID: $END_USER" \
  -H "Content-Type: application/json" \
  -d '{"memory_ids": [10, 11, 12], "lossless": false}'

# link two memories
curl -sS -X POST "$API/memory/10/relations" \
  -H "X-API-Key: $KEY" -H "X-End-User-ID: $END_USER" \
  -H "Content-Type: application/json" \
  -d '{
    "to_memory_id": 11,
    "relationship_type": "supports",
    "confidence": 0.9
  }'

Reading an error response

Errors are JSON with a detail field; rate-limit responses additionally include retry_after. Always inspect the X-Request-ID response header — it is the ticket number for support.

BASH

curl -sSi -X POST "$API/memory/add" \
  -H "X-API-Key: WRONG" -H "Content-Type: application/json" \
  -d '{"text":"x"}' \
  | sed -n '1,/^\r$/p; /detail/p'

Status codes you will see

401/403 from AuthError, 404 from NotFoundError, 400/409/422 from ValidationError, 429 from RateLimitError, 5xx from ServerError.

← Previous

Bulk Operations

REST from Postman