---
title: "Bulk-add episodes to memory graph (maintenance lane)"
description: "Ingest a batch of episodic payloads into one knowledge-graph scope.\n\nThe bulk counterpart to ``POST /memories/graph`` for backfills and other\noperator-driven batches. The batch executes on the maintenance worker\nlane, so it never occupies realtime capacity, while still passing through\nthe written scope's FIFO so it cannot race realtime graph writes.\nEpisodes ingest in order with per-episode idempotency, so a retried batch\nresumes after the last committed episode. Always asynchronous — poll\n``GET /memories/graph/status/{job_id}``."
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

Path: AI Gateway API › Memory

`POST /memories/graph/bulk`

Ingest a batch of episodic payloads into one knowledge-graph scope.

The bulk counterpart to ``POST /memories/graph`` for backfills and other
operator-driven batches. The batch executes on the maintenance worker
lane, so it never occupies realtime capacity, while still passing through
the written scope's FIFO so it cannot race realtime graph writes.
Episodes ingest in order with per-episode idempotency, so a retried batch
resumes after the last committed episode. Always asynchronous — poll
``GET /memories/graph/status/{job_id}``.

## Authentication

- `HTTPBearer`, http, header `Authorization`

## Header parameters

- `X-On-Behalf-Of` (`add_memory_data_bulk.header.X-On-Behalf-Of`; any of, optional)
  - any of: `string`, `null`
- `X-External-User-Id` (`add_memory_data_bulk.header.X-External-User-Id`; any of, optional)
  - any of: `string`, `null`
- `X-App-Id` (`add_memory_data_bulk.header.X-App-Id`; any of, optional)
  - any of: `string`, `null`

## Request body

_Required._

- `episodes` (`add_memory_data_bulk.episodes`; array<object>, required)
  - `data` (`add_memory_data_bulk.episodes.data`; string, required)
    - maxLength 50000
  - `type` (`add_memory_data_bulk.episodes.type`; string, required)
    - one of `"message"`, `"json"`, `"text"`, `"document"`, `"note"`, `"transcribe"`
  - `source_description` (`add_memory_data_bulk.episodes.source_description`; any of, optional)
    - any of: `string`, `null`
  - `created_at` (`add_memory_data_bulk.episodes.created_at`; any of, optional)
    - any of: `string`, `null`
- `agent_id` (`add_memory_data_bulk.agent_id`; any of, optional) — Target the calling user's memory, scoped by this agent. Provide exactly one of agent_id or graph_id.
  - any of: `string`, `null`
- `graph_id` (`add_memory_data_bulk.graph_id`; any of, optional) — Target a shared namespace instead of user memory. Requires a service token.
  - any of: `string`, `null`
- `mode` (`add_memory_data_bulk.mode`; string, optional) — append: sequential ingestion with full edge invalidation against the existing graph. seed: one bulk extraction pass over the batch — the fast path for migrating into a fresh or replaced graph.
  - one of `"append"`, `"seed"`; default `"append"`
- `replace` (`add_memory_data_bulk.replace`; boolean, optional) — Expire the scope's existing memory edges before ingesting (start from fresh). User scopes (agent_id) only.
  - default `false`

## Example request

```json
{
  "episodes": [
    {
      "data": "string",
      "type": "message",
      "source_description": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "agent_id": "string",
  "graph_id": "string",
  "mode": "append",
  "replace": false
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://truememory-api.mvstg.com/memories/graph/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "episodes": [
    {
      "data": "string",
      "type": "message",
      "source_description": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "agent_id": "string",
  "graph_id": "string",
  "mode": "append",
  "replace": false
}
'
```

### TypeScript

```typescript
const url = 'https://truememory-api.mvstg.com/memories/graph/bulk';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    episodes: [
      {
        data: 'string',
        type: 'message',
        source_description: 'string',
        created_at: '2019-08-24T14:15:22Z'
      }
    ],
    agent_id: 'string',
    graph_id: 'string',
    mode: 'append',
    replace: false
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://truememory-api.mvstg.com/memories/graph/bulk"

payload = {
    "episodes": [
        {
            "data": "string",
            "type": "message",
            "source_description": "string",
            "created_at": "2019-08-24T14:15:22Z"
        }
    ],
    "agent_id": "string",
    "graph_id": "string",
    "mode": "append",
    "replace": False
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 202

Successful Response

#### Example

```json
{
  "status": "processing",
  "job_id": "string",
  "episodes": 0
}
```

- `job_id` (`add_memory_data_bulk.response.202.job_id`; string, required) — Poll GET /memories/graph/status/{job_id} with this.
- `episodes` (`add_memory_data_bulk.response.202.episodes`; integer, required) — Number of episodes queued.
- `status` (`add_memory_data_bulk.response.202.status`; string, optional)
  - default `"processing"`

### 422

Validation Error

#### Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

- `detail` (`add_memory_data_bulk.response.422.detail`; array<object>, optional)
  - `loc` (`add_memory_data_bulk.response.422.detail.loc`; array<any of>, required)
    - any of: `string`, `integer`
  - `msg` (`add_memory_data_bulk.response.422.detail.msg`; string, required)
  - `type` (`add_memory_data_bulk.response.422.detail.type`; string, required)
  - `input` (`add_memory_data_bulk.response.422.detail.input`; unknown, optional)
  - `ctx` (`add_memory_data_bulk.response.422.detail.ctx`; object, optional)


Source: https://truememory-docs.mvstg.com/api/memories/graph/bulk/index.md