# `/v3/atomic/*` Endpoints for CRUD Operations on L1 Atomic Memory in TencentDB Agent Memory

> Master TencentDB Agent Memory's v3 atomic endpoints for CRUD operations on L1 Atomic Memory. Learn to create, read, update, delete, count, and search your data efficiently.

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

---

**The L1 Atomic Memory layer exposes five HTTP POST endpoints under `/v3/atomic` for create, read, update, delete, count, and search operations, with up-sert semantics via `POST /v3/atomic/update` and filter-based queries via `POST /v3/atomic/search`.**

The **TencentDB-Agent-Memory** repository implements a tiered memory architecture where L1 Atomic Memory provides structured, key-value storage for discrete data units. This guide covers the complete v3 API surface for atomic operations, referencing the official implementation in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) and SDK documentation in both TypeScript and Python client libraries.

## Complete `/v3/atomic/*` Endpoint Reference

All endpoints follow the `POST /v3/atomic/{operation}` pattern and accept JSON-encoded request bodies. Authentication requires platform-standard headers including `Authorization: Bearer <TOKEN>`.

### Create and Update: `POST /v3/atomic/update`

The **update** endpoint implements **up-sert semantics**—it inserts a new record if the key does not exist, or overwrites the existing record if it does.

```typescript
// TypeScript SDK
await client.updateAtomic({
  key: 'session:12345',
  value: { content: 'Hello world', meta: { ttl: 3600 } },
});

```

```python

# Python SDK

client.update_atomic(
    key='session:12345',
    value={'content': 'Hello world', 'meta': {'ttl': 3600}}
)

```

The `key` parameter serves as the unique identifier. The `value` field accepts arbitrary JSON-serializable objects, enabling flexible schema design.

### Read and Query: `POST /v3/atomic/query`

Retrieve single or batch records by key.

```typescript
const result = await client.queryAtomic({ key: 'session:12345' });

```

```python
result = client.query_atomic(key='session:12345')

```

For batch retrieval, pass an array of keys in the request body.

### Search: `POST /v3/atomic/search`

Execute **filter-based queries** using `WHERE`-style clauses against record attributes.

```typescript
const searchRes = await client.searchAtomic({
  where: "meta.ttl > 0",
  limit: 10,
});

```

```python
search_res = client.search_atomic(where="meta.ttl > 0", limit=10)

```

This endpoint enables bulk retrieval without prior knowledge of specific keys, supporting pagination via `limit` and `offset` parameters.

### Delete: `POST /v3/atomic/delete`

Remove records by key with confirmation of deletion count.

```typescript
const delRes = await client.deleteAtomic({ key: 'session:12345' });
console.log('Deleted count:', delRes.deleted_count);

```

```python
del_res = client.delete_atomic(key='session:12345')
print('Deleted count:', del_res['deleted_count'])

```

### Count: `POST /v3/atomic/count`

Return matching record totals for pagination or health-check scenarios.

```typescript
const cnt = await client.countAtomic({ where: "meta.ttl > 0" });

```

```python
cnt = client.count_atomic(where="meta.ttl > 0")

```

## Architecture and Isolation

The `/v3/atomic/*` endpoints are **strongly isolated** from lower-level data planes (L0, L2, L3) as implemented in the MemoryCore service. This separation provides:

- **Clean API versioning** — v3 guarantees stable contracts for client integrations
- **Independent scaling** — atomic operations route through dedicated gateway configurations
- **Simplified client SDKs** — TypeScript and Python libraries expose typed methods matching each endpoint

Gateway routing is configured in [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml), which maps `/v3/atomic/*` traffic to the Atomic Memory service backend.

## SDK Implementation Details

### TypeScript SDK Reference

The endpoint table in [`sdk/memory-core/typescript/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/README.md) (lines 70–74) documents the complete operation matrix for TypeScript consumers. The `MemoryClient` class provides async methods: `updateAtomic`, `queryAtomic`, `searchAtomic`, `deleteAtomic`, and `countAtomic`.

### Python SDK Reference

The corresponding documentation in [`sdk/memory-core/python/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/README.md) (lines 117–120) mirrors the TypeScript structure. The Python client uses snake_case naming: `update_atomic`, `query_atomic`, `search_atomic`, `delete_atomic`, and `count_atomic`.

Both SDKs handle request serialization, authentication header injection, and response parsing automatically.

## Request and Response Format

| Aspect | Specification |
|--------|---------------|
| **HTTP Method** | POST (all endpoints) |
| **Content-Type** | `application/json` |
| **Authentication** | `Authorization: Bearer <TOKEN>` header required |
| **Key field** | String, unique per record |
| **Value field** | Arbitrary JSON object |
| **Filter syntax** | SQL-like `WHERE` clauses for search/count |
| **Response envelope** | JSON object with result data and metadata |

## Summary

- The **L1 Atomic Memory** `/v3/atomic/*` endpoints provide full CRUD plus search and count functionality
- **Up-sert semantics** via `POST /v3/atomic/update` eliminate separate create vs. update logic
- **Filter-based operations** via `/v3/atomic/search` and `/v3/atomic/count` enable flexible data access patterns
- **Strong isolation** from other memory tiers ensures stable, versioned API contracts
- Official documentation resides in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) with SDK guides in [`sdk/memory-core/typescript/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/README.md) and [`sdk/memory-core/python/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/README.md)

## Frequently Asked Questions

### What is the difference between `/v3/atomic/query` and `/v3/atomic/search`?

**`/v3/atomic/query`** retrieves records by exact key match—use it when you know the specific identifier. **`/v3/atomic/search`** executes attribute-based filtering with `WHERE` clauses—use it for discovery when keys are unknown. Query is optimized for latency; search provides flexibility.

### Does `POST /v3/atomic/update` support partial updates?

No—the update endpoint implements **full up-sert semantics**. The provided `value` completely replaces any existing record. For partial modifications, clients must read the existing record, modify the desired fields, and submit the complete updated value.

### How are the `/v3/atomic/*` endpoints authenticated?

All requests require the platform-standard `Authorization: Bearer <TOKEN>` header. The SDKs automatically inject this header when initialized with valid credentials. Token validation occurs at the gateway layer configured in [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml).

### What data types can I store in L1 Atomic Memory?

The `value` field accepts any **JSON-serializable object**, including nested structures. However, the `where` filter syntax in search/count operations works best with primitive fields (strings, numbers, booleans) and shallow object paths like `meta.ttl`. Complex nested queries may require client-side filtering.