# API Endpoints for Context Offloading and Querying in TencentDB Agent Memory > Discover API endpoints for context offloading and querying in TencentDB Agent Memory. Learn about ingest, query-mmd, and compact endpoints for efficient data management. Access them via REST. - Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) - Tags: api-reference - Published: 2026-09-04 --- **TencentDB Agent Memory exposes three REST endpoints under `/v2/offload/`—`ingest` for pushing context, `query-mmd` for retrieval, and `compact` for maintenance—each requiring Bearer authentication and returning JSON envelopes with unique request IDs.** The TencentCloud/TencentDB-Agent-Memory repository provides a scalable memory service for AI agents that stores contextual data outside the application process. Understanding the API endpoints for context offloading and querying is essential for implementing efficient session management and reducing memory pressure on your agents. ## Core Offload API Endpoints All offload operations route through [`MemoryCore/src/offload_server/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts), which registers handlers for the `/v2/offload/` prefix. The implementation delegates to specific handlers while enforcing common validation and storage resolution logic. ### POST /v2/offload/ingest The `ingest` endpoint accepts payloads containing session texts, embeddings, and metadata for persistent storage. In [`MemoryCore/src/offload_server/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts) (lines 56-64), the router forwards validated requests to `handleIngest`, which writes data to the configured backend. ```bash curl -X POST https:///v2/offload/ingest \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "session_id": "sess-12345", "messages": [ { "role": "user", "content": "How do I reset my password?" }, { "role": "assistant", "content": "You can reset it via the account settings." } ], "metadata": { "app": "my-app" } }' ``` ```javascript // Node.js (fetch) – offload ingestion const fetch = require('node-fetch'); async function ingestContext() { const resp = await fetch('https:///v2/offload/ingest', { method: 'POST', headers: { 'Authorization': 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify({ session_id: 'sess-12345', messages: [ { role: 'user', content: 'How do I reset my password?' }, { role: 'assistant', content: 'You can reset it via the account settings.' } ], metadata: { app: 'my-app' } }) }); const result = await resp.json(); console.log(result); } ingestContext(); ``` ### POST /v2/offload/query-mmd To retrieve offloaded context, clients call the `query-mmd` endpoint. The router validates incoming payloads against `MmdQuerySchema` defined in [`MemoryCore/src/offload_server/schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/schemas.ts) before invoking `handleMmdQuery` (router.ts lines 66-75). The request body must include a `session_id` and optionally accepts a `limit` parameter to control result set size. ```bash curl -X POST https:///v2/offload/query-mmd \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "session_id": "sess-12345", "limit": 10 }' ``` ```javascript // Node.js (fetch) – query offloaded data async function queryContext() { const resp = await fetch('https:///v2/offload/query-mmd', { method: 'POST', headers: { 'Authorization': 'Bearer ', 'Content-Type': 'application/json' }, body: JSON.stringify({ session_id: 'sess-12345', limit: 10 }) }); const result = await resp.json(); console.log(result); } queryContext(); ``` ### POST /v2/offload/compact The `compact` endpoint triggers maintenance operations on stored data to reclaim space and improve lookup performance. Handled by `handleCompaction` (router.ts lines 77-84), this endpoint is typically invoked by administrative processes rather than application code. ```bash curl -X POST https:///v2/offload/compact \ -H "Authorization: Bearer " ``` ## Shared Request Processing Pipeline All three endpoints share common middleware logic implemented in the router file. ### Authentication via parseV2Auth Every request passes through `parseV2Auth`, which extracts the service identifier from request headers. Missing or invalid credentials immediately return HTTP 401, preventing unauthorized access to stored context. ### Storage Adapter Resolution The router obtains a `StorageAdapter` instance via `deps.resolveStorage` (using the authenticated service ID) or falls back to `deps.getStorage` for the default backend. If no storage is available, the API returns HTTP 503 Service Unavailable. ### Request Tracing Each response includes a unique identifier generated by `makeRequestId()` for distributed tracing and debugging purposes. This ID appears in every JSON response envelope, enabling correlation across distributed systems. ## Key Implementation Files The offload API surface consists of the following source files: - [`MemoryCore/src/offload_server/router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts) – Registers routes and dispatches to handlers - [`MemoryCore/src/offload_server/schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/schemas.ts) – Defines `MmdQuerySchema` for request validation - [`MemoryCore/src/offload_server/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/types.ts) – Describes configuration and dependency interfaces - [`MemoryCore/src/offload_server/ingest-handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/ingest-handler.ts) – Implements storage logic for the **ingest** endpoint - [`MemoryCore/src/offload_server/mmd-handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/mmd-handler.ts) – Implements **query-mmd** retrieval logic - [`MemoryCore/src/offload_server/compact/compaction-handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/compact/compaction-handler.ts) – Implements the **compact** maintenance operations ## Summary - **Three REST endpoints** comprise the offload API: `/v2/offload/ingest`, `/v2/offload/query-mmd`, and `/v2/offload/compact` - **Bearer token authentication** is enforced via `parseV2Auth` with 401 responses for invalid credentials - **Storage resolution** uses `deps.resolveStorage` or `deps.getStorage`, returning 503 when backends are unavailable - **Request tracing** is provided via `makeRequestId()` in all response envelopes - **Schema validation** for queries occurs through `MmdQuerySchema` before handler execution ## Frequently Asked Questions ### What authentication method does TencentDB Agent Memory require? The offload API requires Bearer token authentication passed via the `Authorization` header. The `parseV2Auth` function validates these credentials, and requests without valid tokens receive an HTTP 401 response. ### How do I retrieve specific session context from the offload storage? Send a POST request to `/v2/offload/query-mmd` with a JSON body containing the `session_id` you stored during ingestion. You may optionally include a `limit` parameter to restrict the number of returned items. The router validates your payload against `MmdQuerySchema` before executing the query. ### What happens if the storage backend is unavailable? If `deps.resolveStorage` or `deps.getStorage` fails to return a valid `StorageAdapter`, the API responds with HTTP 503 Service Unavailable. This indicates that the memory service cannot currently process the request due to backend connectivity issues. ### When should I use the compact endpoint? The `/v2/offload/compact` endpoint triggers maintenance operations that reclaim storage space and optimize lookup performance. You should schedule this operation during low-traffic periods or as part of automated maintenance routines, as it is handled by `handleCompaction` and may impact performance during execution.