# v3 /v3/conversation/* Endpoints: Add, Query, Search, Delete, and Count Operations Explained

> Explore the TencentDB Agent Memory Core's v3 conversation endpoints: add, query, search, delete, and count. Learn how to manage L0 conversation messages effectively.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: api-reference
- Published: 2026-08-31

---

**The Memory Core service exposes five ops-only HTTP endpoints under `/v3/conversation/`—**add**, **query**, **search**, **delete**, and **count**—that manage L0 conversation messages with a unified response envelope.**

The **TencentDB-Agent-Memory** repository provides a complete v3 API surface for managing L0 (conversation-level) message storage. These `/v3/conversation/*` endpoints form the foundation of the memory layer, enabling agents to persist dialogue history, retrieve paginated records, perform full-text search, prune obsolete data, and obtain usage statistics. All five operations share a consistent contract: they accept JSON request bodies, return envelopes with `code`, `message`, and `data` fields, and treat `code: 0` as success.

---

## Endpoint Overview

| Operation | HTTP Method | Path | Purpose |
|-----------|-------------|------|---------|
| **Add** | `POST` | `/v3/conversation/add` | Append one or multiple L0 messages to a session |
| **Query** | `POST` | `/v3/conversation/query` | Paginated retrieval with filtering by session, time range, etc. |
| **Search** | `POST` | `/v3/conversation/search` | Keyword-based full-text search across messages |
| **Delete** | `POST` | `/v3/conversation/delete` | Batch removal of messages or entire sessions |
| **Count** | `POST` | `/v3/conversation/count` | Return total matching messages with optional filters |

The authoritative specification lives in [[`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/v3-api-memorycore-doc.md) at lines 9–76.

---

## POST /v3/conversation/add: Writing L0 Messages

The **add** endpoint persists conversation turns and triggers asynchronous L1 extraction pipelines for downstream memory layers.

### Request Body Schema

```json
{
  "session_id": "string",
  "messages": [
    {
      "role": "user|assistant",
      "content": "string (1-8192 chars)",
      "timestamp": "ISO-8601? (optional)",
      "recorded_at": "ISO-8601? (optional)"
    }
  ],
  "team_id": "string?",
  "agent_id": "string?",
  "user_id": "string?",
  "task_id": "string?"
}

```

- **`session_id`** (required): Business session identifier
- **`messages`**: Array of 1–100 message objects
- **Isolation fields**: v3 enforces `team_id` + `agent_id` + `user_id` for multi-tenant boundaries

### Response Data Fields

| Field | Type | Description |
|-------|------|-------------|
| `accepted_ids` | `string[]` | Storage identifiers for accepted messages |
| `accepted_versions` | `string[]` | Version tags (currently always `"v1"`) |
| `total_count` | `number` | Count of messages successfully stored |

### cURL Example

```bash
curl -X POST http://localhost:8420/v3/conversation/add \
  -H "Content-Type: application/json" \
  -d '{"session_id":"sess_1","messages":[{"role":"user","content":"帮我看看这个 bug"}]}'

```

---

## POST /v3/conversation/query: Paginated Retrieval

The **query** endpoint lists stored messages with cursor-style pagination and temporal filtering.

### Request Parameters (All Optional)

| Field | Type | Default / Limits |
|-------|------|----------------|
| `session_id` | `string` | — |
| `limit` | `number` | 20 (max 100) |
| `offset` | `number` | — |
| `time_start` / `time_end` | `string` (ISO-8601) | — |
| `team_id`, `agent_id`, `user_id` | `string` | Tenant isolation |

### Response Structure

```json
{
  "messages": [
    {
      "id": "string",
      "version": "string",
      "role": "user|assistant",
      "content": "string",
      "timestamp": "string?",
      "recorded_at": "string?",
      "session_id": "string?",
      "team_id": "string?",
      "user_id": "string?",
      "agent_id": "string?"
    }
  ],
  "total": "number"
}

```

### cURL Example

```bash
curl -X POST http://localhost:8420/v3/conversation/query \
  -H "Content-Type: application/json" \
  -d '{"session_id":"sess_1","limit":10}'

```

---

## POST /v3/conversation/search: Full-Text Search

The **search** endpoint performs relevance-scored keyword matching across message contents.

### Request Body

| Field | Type | Required |
|-------|------|----------|
| `query` | `string` (1-2048 chars) | **Yes** |
| `limit` | `number` (default 5, max 100) | No |
| `session_id` | `string` | No |
| `time_start` / `time_end` | `string` (ISO-8601) | No |
| Isolation fields | `string` | No |

### Response with Relevance Scores

```json
{
  "messages": [
    {
      "id": "string",
      "role": "user|assistant",
      "content": "string",
      "score": "number"
    }
  ]
}

```

The **`score`** field indicates textual relevance for ranking results.

### cURL Example

```bash
curl -X POST http://localhost:8420/v3/conversation/search \
  -H "Content-Type: application/json" \
  -d '{"query":"bug","limit":5}'

```

---

## POST /v3/conversation/delete: Batch Removal

The **delete** endpoint supports two mutually exclusive bulk deletion modes.

### Deletion Modes (Supply Exactly One)

| Field | Type | Constraint |
|-------|------|------------|
| `message_ids` | `string[]` | ≤ 5,000 IDs |
| `session_ids` | `string[]` | ≤ 100 IDs |
| `session_id` | `string` | *Deprecated*—use `session_ids` |

### Response

```json
{
  "deleted_count": "number"
}

```

### cURL Example

```bash
curl -X POST http://localhost:8420/v3/conversation/delete \
  -H "Content-Type: application/json" \
  -d '{"message_ids":["msg_1","msg_2"]}'

```

---

## POST /v3/conversation/count: Usage Statistics

The **count** endpoint returns aggregated totals for capacity planning and UI pagination.

### Request Filters (All Optional)

| Field | Type |
|-------|------|
| `session_id` | `string` |
| `time_start` / `time_end` | `string` (ISO-8601) |
| Isolation fields | `string` |

### Response

```json
{
  "total": "number"
}

```

### cURL Example

```bash
curl -X POST http://localhost:8420/v3/conversation/count \
  -H "Content-Type: application/json" \
  -d '{"session_id":"sess_1"}'

```

---

## TypeScript SDK Usage

The [[`sdk/memory-core/typescript/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/README.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/README.md) provides typed client methods that mirror these five endpoints exactly.

```typescript
import { MemoryCoreClient } from '@tencentdb/memory-core';

const client = new MemoryCoreClient({ baseURL: 'http://localhost:8420' });

async function workflow() {
  // Add messages
  await client.addConversation({
    session_id: 'sess_1',
    messages: [{ role: 'user', content: '帮我看看这个 bug' }]
  });

  // Query with pagination
  const query = await client.queryConversation({
    session_id: 'sess_1',
    limit: 5
  });

  // Search by keyword
  const search = await client.searchConversation({ query: 'bug' });

  // Delete by IDs from query results
  const ids = query.data.messages.map(m => m.id);
  await client.deleteConversation({ message_ids: ids });

  // Verify count
  const count = await client.countConversation({ session_id: 'sess_1' });
  console.log('Remaining messages:', count.data.total);
}

```

Python equivalents are documented in [[`sdk/memory-core/python/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/README.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/python/README.md).

---

## Summary

- **`/v3/conversation/add`** persists 1–100 messages per call and triggers async L1 extraction
- **`/v3/conversation/query`** retrieves paginated message histories with optional time bounding
- **`/v3/conversation/search`** executes relevance-scored full-text search across content fields
- **`/v3/conversation/delete`** removes batches of messages (≤ 5,000) or sessions (≤ 100)
- **`/v3/conversation/count`** returns filtered totals for all matching L0 records
- All endpoints use `POST`, return unified envelopes, and respect `team_id`/`agent_id`/`user_id` isolation in v3

---

## Frequently Asked Questions

### What is the maximum number of messages per add request?

The `/v3/conversation/add` endpoint accepts 1–100 messages in a single `messages` array. Requests exceeding this limit are rejected before processing.

### How do I delete an entire session instead of individual messages?

Pass the `session_ids` array (max 100 IDs) rather than `message_ids`. The deprecated `session_id` string parameter should be avoided in favor of the plural form.

### Does the search endpoint support filtering by time range?

Yes. Supply optional `time_start` and `time_end` ISO-8601 strings alongside the required `query` parameter to constrain results temporally.

### Where are the official API contracts documented?

The **Memory Core v3 API documentation** at [[`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/v3-api-memorycore-doc.md) provides complete request/response schemas, with line references to each endpoint's specification.