Getting Started

Quickstart (5 min)

The shortest path from an API key to a successful /memory/add and /memory/query. Raw HTTP, real headers, real body fields.

Before you begin

An API key from the dashboard (Settings → API Keys) or a Bearer token returned by POST /auth/login.
A target project. Project-scoped routes require X-Project-ID unless the API key is already pinned to a project.
If you call the memory API with an API key, include X-End-User-ID so the backend can resolve the owner of the memory.

Check the API is reachable

BASH

curl https://api.memorysync.io/health

Headers you actually need

Header	When to send it	Verified behaviour
`X-API-Key`	Service-to-service calls	Primary header for API-key auth.
`Authorization: Bearer ...`	Browser or session calls	Alternative auth path using the JWT returned by `/auth/login`.
`X-Project-ID`	Project-scoped routes	Required unless the presented API key is already locked to a project.
`X-End-User-ID`	API-key memory calls	Required for service-auth memory requests so memories stay scoped to one human user.
`Content-Type: application/json`	JSON requests	Used by both add and query payloads.

Store one memory

BASH

curl -X POST https://api.memorysync.io/memory/add \
  -H "X-API-Key: $MEMORYSYNC_API_KEY" \
  -H "X-Project-ID: $MEMORYSYNC_PROJECT_ID" \
  -H "X-End-User-ID: demo-user-001" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "User prefers dark mode and compact tables.",
    "source": "quickstart",
    "metadata": {"origin": "docs"}
  }'

Query it back

BASH

curl -X POST https://api.memorysync.io/memory/query \
  -H "X-API-Key: $MEMORYSYNC_API_KEY" \
  -H "X-Project-ID: $MEMORYSYNC_PROJECT_ID" \
  -H "X-End-User-ID: demo-user-001" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What interface preferences does this user have?",
    "k": 5
  }'

Success and non-success response shapes

Case	HTTP	What the backend returns
Stored memory	201	`MemoryResponse` with fields such as `id`, `user_id`, `text`, `source`, `metadata`, and timestamps.
Quota silent mode on add	200	`{"status":"ok"}`.
Extractor stored nothing	200	`{"status":"skipped", ...}` when the extraction pipeline produced no record.
Quota silent mode on query	200	`{"memories": []}`.
Validation failure	422	Structured request validation error payload.

Before you begin

Check the API is reachable

Headers you actually need

Store one memory

Query it back

Success and non-success response shapes

Read next