# API Endpoints for Managing Atomic Memory in TencentDB Agent Memory

> Discover the five POST API endpoints in TencentDB Agent Memory for managing atomic L1 memory records. Create, query, search, delete, and count records with ease. Learn more now.

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

---

**TencentDB Agent Memory exposes five POST endpoints under the `/v3/atomic/*` namespace that enable creating, querying, hybrid searching, bulk deleting, and counting atomic (L1) memory records.**

The TencentDB Agent Memory repository provides a RESTful gateway for manipulating atomic memory through a standardized HTTP interface. These API endpoints for managing atomic memory are defined in the core router and represent the sole public access layer for L1 storage operations. All requests require tenancy headers and utilize the `ApiResponseEnvelope` format for consistent request and response handling.

## Available Endpoints for Atomic Memory Operations

The atomic memory interface exposes five distinct operations, all using the POST method to support complex query bodies and large vector payloads.

| Operation | Path | Primary Function |
|-----------|------|------------------|
| **Update** | `/v3/atomic/update` | Creates new records or overwrites existing ones by `record_id` |
| **Query** | `/v3/atomic/query` | Retrieves paginated lists filtered by metadata, type, or time ranges |
| **Search** | `/v3/atomic/search` | Executes hybrid vector-plus-keyword similarity searches with scores |
| **Delete** | `/v3/atomic/delete` | Removes up to 5,000 records atomically per request |
| **Count** | `/v3/atomic/count` | Returns the total number of records matching filter criteria |

### Updating and Overwriting Records

The `/v3/atomic/update` endpoint accepts a JSON payload containing the `record_id` and updated fields such as `content`, `tags`, or `version`. This operation is idempotent and mapped to the `handleAtomicUpdate` function within the gateway router.

### Querying versus Hybrid Search

Use `/v3/atomic/query` for traditional filtering with pagination parameters. For semantic retrieval combined with keyword matching, the `/v3/atomic/search` endpoint performs hybrid similarity searches, returning results that include scored `items` arrays.

### Bulk Deletion Constraints

The `/v3/atomic/delete` endpoint processes arrays of record IDs with a hard limit of **5,000 identifiers per request**. This ensures atomic removal operations while preventing payload size violations.

## Request Format and Tenancy Isolation

All atomic memory endpoints enforce strict multi-tenancy through required HTTP headers. You must include `x-tdai-service-id` (representing the service boundary) along with optional team and user identifiers to isolate data boundaries. Request bodies must conform to the **ApiResponseEnvelope** structure, with endpoint-specific payloads nested within the standardized wrapper.

## Source Code Architecture

According to the TencentDB Agent Memory source code, the routing logic resides in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts). Lines 59-63 define the **V3-allowed sub-paths** list that authorizes the `/v3/atomic/*` routes, while lines 419-423 map each path to its concrete handler implementation:

- **`handleAtomicUpdate`** processes `/v3/atomic/update` requests
- **`handleAtomicQuery`** processes `/v3/atomic/query` requests  
- **`handleAtomicSearch`** processes `/v3/atomic/search` requests
- **`handleAtomicDelete`** processes `/v3/atomic/delete` requests
- **`handleAtomicCount`** processes `/v3/atomic/count` requests

Runtime payload validation relies on Zod schemas defined in [`MemoryCore/src/gateway/generated/schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/schemas.ts). TypeScript interfaces for client SDKs are exported from [`MemoryCore/src/gateway/generated/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/types.ts).

## Practical Code Examples

The following TypeScript examples demonstrate authenticated requests to the atomic memory endpoints using standard `fetch`:

```typescript
// Update or create an atomic memory record
await fetch('https://your-host/v3/atomic/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-tdai-service-id': 'svc-123',
  },
  body: JSON.stringify({
    record_id: 'rec-456',
    content: { title: 'New title', body: 'Updated text' },
  }),
});

```

```typescript
// Perform hybrid vector + keyword search
await fetch('https://your-host/v3/atomic/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-tdai-service-id': 'svc-123',
  },
  body: JSON.stringify({
    query: 'machine learning',
    top_k: 10,
  }),
});

```

## Summary

- **Five POST endpoints** under `/v3/atomic/*` provide complete lifecycle management for atomic memory records in TencentDB Agent Memory.
- **Bulk deletion** supports up to 5,000 record IDs per request via `/v3/atomic/delete`.
- **Hybrid search** capabilities combine vector similarity and keyword matching through `/v3/atomic/search`, returning scored results.
- **Tenancy isolation** requires `x-tdai-service-id` headers parsed by the gateway in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts).
- **Request validation** relies on Zod schemas in [`MemoryCore/src/gateway/generated/schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/schemas.ts).

## Frequently Asked Questions

### What is the maximum number of records I can delete in a single API call?

The `/v3/atomic/delete` endpoint accepts an array of record IDs with a maximum limit of **5,000 identifiers per request**. Exceeding this threshold will result in a validation error, requiring you to batch deletions across multiple calls.

### Are there GET endpoints available for querying atomic memory?

No, all API endpoints for managing atomic memory use the **POST** method exclusively, including query and count operations. This design supports complex JSON filter bodies and large vector payloads that exceed URL length limitations.

### How does the hybrid search endpoint differ from standard query?

The `/v3/atomic/search` endpoint executes **vector similarity searches combined with keyword filtering**, returning results with relevance scores. In contrast, `/v3/atomic/query` performs traditional metadata filtering by type, time range, or tags without semantic similarity calculation.

### Where are the TypeScript types for these endpoints defined?

TypeScript interfaces and client contracts reside in [`MemoryCore/src/gateway/generated/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/types.ts). Runtime validation schemas are located in [`MemoryCore/src/gateway/generated/schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/schemas.ts) adjacent to the router implementation in [`v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v2-router.ts).