API Reference

Bulk Add Memory

Ingest up to 50 memory candidates in a single request. Each item is run through the same extraction pipeline as POST /memory/add, so dedup, validation, and low-signal filtering apply. The response uses 207 Multi-Status because partial success is expected — every item is reported individually.

POST/memory/bulk-add

Authentication

Accepts a JWT bearer token (Authorization: Bearer eyJ…) or an API key (X-API-Key: ms_live_…). API-key callers should send X-Project-ID unless the key is project-locked. Cross-tenant operators must send X-Tenant-ID.

Request body

Field	Type	Required	Description
`items`	`object[]`	required	Array of `1..50` candidates. Each item: `text` (required), plus optional `source`, `event_type`, `tags`, `metadata`, `importance`, `end_user_id`.
`deduplicate`	`boolean`	optional	Default `true`. Skip storage when a near-duplicate already exists for the user.

request.json

{
  "items": [
    {
      "text": "User prefers dark mode.",
      "source": "chat",
      "tags": [
        "preferences"
      ]
    },
    {
      "text": "Lives in Austin.",
      "source": "profile",
      "importance": 0.4
    }
  ]
}

Response

Returns 200 OK with the following body.

Field	Type	Required	Description
`total`	`integer`	optional	Items submitted.
`created`	`integer`	optional	Items that produced at least one stored memory.
`skipped`	`integer`	optional	Items deduped or filtered as low-value.
`rejected`	`integer`	optional	Items that failed validation or ingest.
`results`	`object[]`	optional	Per-item rows: `{ index, status: created\|skipped\|rejected, memory_ids, reason }`.

200.json

{
  "total": 2,
  "created": 1,
  "skipped": 1,
  "rejected": 0,
  "results": [
    {
      "index": 0,
      "status": "created",
      "memory_ids": [
        184213
      ],
      "reason": null
    },
    {
      "index": 1,
      "status": "skipped",
      "memory_ids": [],
      "reason": "no_high_value_content"
    }
  ]
}

Errors

Status	Code	Description
400	`validation_error`	Body or query failed schema validation. The error includes the offending `field` name.
401	`unauthenticated`	Missing or invalid bearer token / API key.
403	`forbidden`	Authenticated principal lacks the required scope, role, or project access.
404	`not_found`	Target resource does not exist or is not visible to the calling tenant.
429	`rate_limited`	Per-IP or per-route limit exceeded. Respect the `Retry-After` header.
500	`internal_error`	Unhandled server error. Quote the `request_id` when contacting support.

Examples

cURL

curl -X POST https://api.memorysync.io/memory/bulk-add \
  -H "Authorization: Bearer $MEMORYSYNC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "text": "User prefers dark mode.",
      "source": "chat",
      "tags": [
        "preferences"
      ]
    },
    {
      "text": "Lives in Austin.",
      "source": "profile",
      "importance": 0.4
    }
  ]
}'

javascript

import { MemorySync } from 'memorysync'

const client = new MemorySync({ apiKey: process.env.MEMORYSYNC_KEY })

const result = await client.request({
  method: 'POST',
  path: '/memory/bulk-add',
  body: {
    "items": [
      {
        "text": "User prefers dark mode.",
        "source": "chat",
        "tags": [
          "preferences"
        ]
      },
      {
        "text": "Lives in Austin.",
        "source": "profile",
        "importance": 0.4
      }
    ]
  },
})
console.log(result)

python

from memorysync import Client

client = Client(api_key=os.environ["MEMORYSYNC_KEY"])

result = client.request(
    method="POST",
    path="/memory/bulk-add",
    json={
      "items": [
        {
          "text": "User prefers dark mode.",
          "source": "chat",
          "tags": [
            "preferences"
          ]
        },
        {
          "text": "Lives in Austin.",
          "source": "profile",
          "importance": 0.4
        }
      ]
    },
)
print(result)

Behavior & notes

HTTP status is 207 Multi-Status. Required scope: memories:write. API-key callers must supply end_user_id on each item (or via X-End-User-ID). Rejected items do not abort the batch.

← Previous

Add Memory

Query Memory