Agentic Memory, agent memory service - OpenSearch - Alibaba Cloud Documentation Center

Provides long-term, short-term, and contextual memory storage and retrieval for Agentic AI agents and intelligent search services. Supports storage, query, update, and deletion of three data types: personalized Memory, reusable Skill, and Knowledge Base. Uses hybrid retrieval combining BM25 and vector search with multi-way recall for efficient and accurate results.

Service name

Service ID

Description

API QPS limit (including primary account and RAM users)

Agentic Memory

agentic-memory

Provides storage and management for three data types: Memory (V4), Skill (V3), and Knowledge Base (V3). Memory stores long-term memories such as user personal preferences. Skill stores reusable execution logic and skills. Knowledge Base stores knowledge assets in document form.

To increase the QPS limit, submit a ticket to technical support.

API versioning

The Memory API URI prefix is /v4/openapi/workspaces/{workspace_name}/.

The Skill and Knowledge Base API URI prefix is /v3/openapi/workspaces/{workspace_name}/.

The health check API is under the Service status category, using the V3 prefix /v3/openapi/workspaces/{workspace_name}/.

Prerequisites

Obtain authentication credentials
When calling AI Search Platform services through APIs, caller identity authentication is required. For information about how to obtain authentication credentials, see Obtain authentication credentials.
Obtain the service endpoint
You can call the service through the public network or a VPC. For more information, see Obtain the service endpoint.

Common request

Common URI

Memory API (V4):

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}

Skill / Knowledge Base / health check API (V3):

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}

Parameter description:

host: The service endpoint. You can call the API through the public network or a VPC. For more information, see Obtain the service endpoint.
workspace_name: The workspace name, for example, default.
service_id: The service ID. The fixed value is agentic-memory.

Header parameters

API-KEY authentication

Parameter	Type	Required	Description	Example
Content-Type	String	Yes	Request type: application/json	application/json
Authorization	String	Yes	API-Key	Bearer OS-d1**2a

Memory API (V4)

For all Memory operations in this section, the URI prefix is /v4/openapi/workspaces/{workspace_name}/memory/{service_id}. The Memory async event ID prefix is me-.

Store Memory

Intelligently extracts user preference information from message content and stores it as Memory. The storage process is asynchronous. The API returns an event ID (event_id). You can retrieve the processing result through the query task status API. The system automatically searches existing memories, deduplicates, and determines whether to add or update.

Request method

POST

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/add

Body parameters

Parameter	Type	Required	Description	Example
messages	String/Object/Array	Yes	The message content. Supports three formats: String (plain text), Object (single message), and Array (multi-turn conversation).	String: `"I like drinking coffee"` Object: `{ "role": "user", "content": "I like drinking coffee" }` Array (multi-turn conversation): `[ {"role": "user", "content": "I like drinking coffee, please give me some recommendations"}, {"role": "assistant", "content": "I recommend Americano for you..."} ]`
user_id	String	Yes	The user ID.	user_123
agent_id	String	No	The agent ID, used only as a filter dimension.	agent_001
run_id	String	No	The run ID, used only as a filter dimension.	run_001
metadata	Object	No	Custom key-value pairs stored together with the Memory. Can be used to tag business fields such as source and category.	{"source": "example"}
infer	Boolean	No	Whether to perform semantic extraction on the message to generate Memory. Defaults to true, which means the system intelligently extracts key information. If set to false, the original text is stored as a whole.	true

Response parameters

Parameter	Type	Description	Example
event_id	String	The async event ID, with the prefix me-. You can retrieve the processing result through the query task status API.	me-06bde8b5-d123-43cf-9898-64d08fbfaafc
status	String	The initial event status, fixed to PENDING.	PENDING
message	String	The prompt message.	Memory creation accepted; poll the event endpoint for status.

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/add' \
--header 'Authorization: Bearer your-API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    {"role": "user", "content": "I like drinking coffee, recommend something for me"},
    {"role": "assistant", "content": "I recommend an Americano for you..."}
  ],
  "user_id": "user_123",
  "metadata": {"source": "example"}
}'

Sample response

{
  "message": "Memory creation accepted; poll the event endpoint for status.",
  "status": "PENDING",
  "event_id": "me-06bde8b5-d123-43cf-9898-64d08fbfaafc"
}

Query event status

Queries the processing status of the async event that stores Memory and the list of generated memories.

Request method

GET

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/events/{event_id}

Path parameters

Parameter	Type	Required	Description	Example
event_id	String	Yes	The event ID returned when storing Memory, with the prefix me-.	me-06bde8b5-d123-43cf-9898-64d08fbfaafc

Response parameters

Parameter	Type	Description	Example
id	String	The event ID.	me-06bde8b5-d123-43cf-9898-64d08fbfaafc
status	String	The event status. Valid values: PENDING (to be processed), SUCCEEDED (processing completed), and FAILED (processing failed).	SUCCEEDED
results	Array	The list of Memory IDs generated after processing is completed.	["m-8d0417d7-9368-4777-9016-b7ee6daeb70b"]

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/events/me-06bde8b5-d123-43cf-9898-64d08fbfaafc' \
--header 'Authorization: Bearer your-API-KEY'

Sample response

{
  "id": "me-06bde8b5-d123-43cf-9898-64d08fbfaafc",
  "status": "SUCCEEDED",
  "results": [
    "m-8d0417d7-9368-4777-9016-b7ee6daeb70b",
    "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04"
  ]
}

Search Memory

Searches memories based on query conditions, using BM25 and vector multi-way recall.

Request method

POST

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/search

Body parameters

Parameter	Type	Required	Description	Example
query	String	Yes	The search keyword.	coffee
filters	Object	Yes	The filter conditions. user_id is required. agent_id and run_id are optional. They are combined with AND.	`{ "AND": [ { "user_id": "user_123" }, { "agent_id": "agent_123" } ] }`
top_k	Int	No	The lower and upper limits of the number of returned results. The lower limit is 1 and the upper limit is 1000.	10
threshold	Float	No	The similarity threshold, ranging from 0 to 1. Results with a score below this value are not returned.	0.5

Response parameters

Parameter	Type	Description	Example
results	Array	The list of matched memories. Each entry contains fields such as id, memory, score, metadata, created_at, and updated_at.	-
results[].id	String	The Memory ID, with the prefix m-.	m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04
results[].memory	String	The memory content.	The assistant recommended an Americano to the user
results[].score	Float	The relevance score (0 to 1).	0.9151
results[].metadata	Object	The custom key-value pairs carried at storage time.	{"source": "example"}
results[].created_at	String	The creation time, in ISO 8601 format.	2026-06-02T08:39:21.482047Z
results[].updated_at	String	The last update time, in ISO 8601 format.	2026-06-02T08:39:21.482047Z

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/search' \
--header 'Authorization: Bearer your-API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "query": "coffee",
  "filters": {"AND": [{"user_id": "user_123"}]},
  "top_k": 10
}'

Sample response

{
  "results": [
      {
        "id": "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04",
        "memory": "The assistant recommended an Americano to the user",
        "score": 0.9151,
        "metadata": {"source": "example"},
        "created_at": "2026-06-02T08:39:21.482047Z",
        "updated_at": "2026-06-02T08:39:21.482047Z"
      }
    ]
  }
}

Get Memory

Retrieves the details of a single Memory by Memory ID.

Request method

GET

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/{memory_id}

Path parameters

Parameter	Type	Required	Description	Example
memory_id	String	Yes	The Memory ID, with the prefix m-.	m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04

Response parameters

The response contains fields such as id, memory, user_id, agent_id, run_id, metadata, created_at, and updated_at. The field definitions are the same as a single record in the response of Search Memory.

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04' \
--header 'Authorization: Bearer your-API-KEY'

Sample response

{
  "id": "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04",
  "memory": "The assistant recommended an Americano to the user",
  "user_id": "user_123",
  "agent_id": "agent_001",
  "run_id": "run_001",
  "metadata": {"source": "example"},
  "created_at": "2026-06-02T08:39:21.482047Z",
  "updated_at": "2026-06-02T08:39:21.482047Z"
}

Update Memory

Updates existing memory content or appends metadata by Memory ID.

Request method

PUT

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/{memory_id}

Body parameters

Parameter	Type	Required	Description	Example
text	String	Yes	The updated memory content.	The assistant recommended a latte to the user
metadata	Object	No	Custom key-value pairs. You can append or overwrite business fields.	{"category": "updated"}

Sample curl request

curl --location --request PUT 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04' \
--header 'Authorization: Bearer your-API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "text": "The assistant recommended a latte to the user",
  "metadata": {"category": "updated"}
}'

Sample response

{
  "id": "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04",
  "text": "The assistant recommended a latte to the user",
  "user_id": "user_123",
  "agent_id": "agent_001",
  "run_id": "run_001",
  "metadata": {"source": "example", "category": "updated"},
  "created_at": "2026-06-02T08:39:21.482047Z",
  "updated_at": "2026-06-02T08:40:18.428159Z"
}

Delete Memory

Deletes a Memory by Memory ID. The returned message indicates the deletion result.

Request method

DELETE

URL

{host}/v4/openapi/workspaces/{workspace_name}/memory/{service_id}/memories/{memory_id}

Sample curl request

curl --location --request DELETE 'http://****-hangzhou.opensearch.aliyuncs.com/v4/openapi/workspaces/default/memory/agentic-memory/memories/m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04' \
--header 'Authorization: Bearer your-API-KEY'

Sample response

{
  "message": "Memory m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04 deleted successfully"
}

Skill API (V3)

For all Skill operations in this section, the URI prefix is /v3/openapi/workspaces/{workspace_name}/memory/{service_id}. The Skill async task ID prefix is st-.

Extract and store Skill

Intelligently extracts reusable skills (Skill) from multi-turn conversations and stores them. Processing is an async task. The API returns a task ID. You can retrieve the result through the query Skill task status API.

Request method

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/add

Body parameters

Parameter	Type	Required	Description	Example
messages	Array	Yes	The list of multi-turn conversation messages. Only the Array format is supported.	[{"role":"user","content":"..."},{"role":"assistant","content":"..."}]
user_id	String	Yes	The user ID.	user_123
agent_id	String	No	The agent ID.	agent_001

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/add' \
--header 'Authorization: Bearer your-API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    {"role": "user", "content": "Unify the login failure message text"},
    {"role": "assistant", "content": "Unify the login failure message across the three clients to: Incorrect login information, please try again"}
  ],
  "user_id": "user_123"
}'

Sample response

{
  "request_id": "3bb081b08c7e4fc8516d26f647f0b2bc",
  "latency": 1659,
  "status": "OK",
  "result": {
    "task_id": "st-73a7c2f1-5600-435e-a4a2-7a9dff6186cf"
  }
}

Upload Skill (ZIP package import)

Uploads Skills in bulk through a ZIP package. Returns the number of successfully imported Skills and a list of metadata.

Request method

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/import

Body parameters

Parameter	Type	Required	Description	Example
zip_base64	String	Yes	The Base64-encoded content of the ZIP file.
user_id	String	Yes	The user ID.	user_123
agent_id	String	No	The agent ID.	agent_001

Response parameters

Parameter	Type	Description	Example
result.imported_count	Int	The number of successfully imported Skills.	1
result.data	Array	The list of imported Skills. Each Skill contains the following fields.	-
result.data[].id	String	The Skill ID, with the prefix s-. Can be used as the skill_id parameter for the get, update, and delete Skill APIs.	s-8f9ac898-820b-4ac5-b981-88c7a7f0edae
result.data[].name	String	The Skill name, from the name field in SKILL.md within the ZIP.	Upload test skill
result.data[].description	String	The Skill description, from the description field in SKILL.md.	Verify the response field structure of the upload Skill API through doctest
result.data[].version	String	The Skill version, from the version field in SKILL.md.	0.2.0
result.data[].owner	String	The Skill owner, taken from the user_id in the request body.	user_123
result.data[].tags	Array of String	The list of Skill tags, from the tags field in SKILL.md.	["test", "doc"]
result.data[].triggers	Array of String	The list of Skill trigger keywords, from the triggers field in SKILL.md.	["test upload", "verify upload"]
result.data[].resource_paths	Array of String	The list of relative paths of resource files in the ZIP other than SKILL.md (such as _meta.json, scripts/, references/). SKILL.md is parsed as the entry point and is not in this list.	["_meta.json", "scripts/echo.py", "references/notes.md"]
result.data[].updated_at	String	The time when the Skill was stored or updated, in ISO 8601 format (with time zone offset).	2026-06-02T09:17:57+00:00

Sample curl request

curl -X POST --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/import' \
--header 'Authorization: Bearer your-API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "zip_base64": "<Base64-encoded ZIP file content>",
  "user_id": "user_123"
}'

Sample response

{
  "request_id": "18d236243f851d13c6fd456743fbec8a",
  "latency": 246,
  "status": "OK",
  "result": {
    "imported_count": 1,
    "data": [
      {
        "id": "s-8f9ac898-820b-4ac5-b981-88c7a7f0edae",
        "name": "Upload test skill",
        "description": "Verify the response field structure of the upload Skill API through doctest",
        "version": "0.2.0",
        "owner": "user_123",
        "tags": ["test", "doc"],
        "triggers": ["test upload", "verify upload"],
        "resource_paths": ["_meta.json", "scripts/echo.py", "references/notes.md"],
        "updated_at": "2026-06-02T09:17:57+00:00"
      }
    ]
  }
}

Query Skill task status

Queries the processing status of the async task that extracts/stores Skill and the list of generated Skill IDs.

Request method

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/tasks/{task_id}

Response parameters

The response contains result.task_id, result.status (pending/running/completed/failed), result.skill_ids (the list of generated Skill IDs), and result.error_message.

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/tasks/st-73a7c2f1-5600-435e-a4a2-7a9dff6186cf' \
--header 'Authorization: Bearer your-API-KEY'

Sample response

{
  "request_id": "2c941feb3468ff5d6ef229204734cddb",
  "latency": 3,
  "status": "OK",
  "result": {
    "task_id": "st-73a7c2f1-5600-435e-a4a2-7a9dff6186cf",
    "status": "completed",
    "skill_ids": ["s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166"]
  }
}

Search Skill

Searches Skills based on query conditions. The body parameters query and user_id are required. agent_id and size (default 10) are optional. The response result.results[] contains skill_id, name, description, version, user_id, and agent_id.

Request method

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/search

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/search' \
--header 'Authorization: Bearer your-API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "query": "login message",
  "user_id": "user_123",
  "size": 10
}'

Sample response

{
  "request_id": "74b5ab4d470e4b7a7811b1b6e7d79c07",
  "latency": 142,
  "status": "OK",
  "result": {
    "results": [
      {
        "skill_id": "s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166",
        "name": "Test skill",
        "description": "Skill for documentation testing",
        "version": "0.1.0",
        "user_id": "user_123"
      }
    ]
  }
}

Get Skill

Retrieves the details of a single Skill by Skill ID, including the content of files such as SKILL.md. The response contains result.skill_id, result.name, result.version, result.files, result.user_id, and result.agent_id.

Request method

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/{skill_id}

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166' \
--header 'Authorization: Bearer your-API-KEY'

Sample response

{
  "request_id": "6d46c81b462f5ec93b94281d5be1ca3a",
  "latency": 89,
  "status": "OK",
  "result": {
    "skill_id": "s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166",
    "name": "Test skill",
    "version": "0.1.0",
    "files": {
      "SKILL.md": "---\nid: \"s-c0e6aaf9-...\"\nname: \"Test skill\"\nversion: \"0.1.0\"\n---\n# Test skill"
    },
    "user_id": "user_123",
    "agent_id": ""
  }
}

Update Skill

Updates the information of a specified Skill. You can update one or more fields individually. user_id is required in the body. Other fields (name, version, files, agent_id, description, tags) are passed in as needed. The response structure is the same as get Skill.

Request method

PUT

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/{skill_id}

Sample curl request

curl -X PUT --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166' \
--header 'Authorization: Bearer your-API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "version": "1.0",
  "user_id": "user_123"
}'

Sample response

{
  "request_id": "224c2313-7b70-47f7-8748-8f583d7b9ae1",
  "latency": 284,
  "status": "OK",
  "result": {
    "name": "Unify multi-client login failure message text",
    "version": "1.0",
    "files": {
      "SKILL.md": "---\nid: \"s-c0e6aaf9-...\"\nname: \"Unify multi-client login failure message text\"\n..."
    }
  }
}

Delete Skill

Deletes a Skill by Skill ID. The response contains result.skill_id, result.status, and result.message.

Request method

DELETE

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/skills/{skill_id}

Sample curl request

curl --location --request DELETE 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/skills/s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166' \
--header 'Authorization: Bearer your-API-KEY'

Sample response

{
  "request_id": "477bdd93f61dfb229452febd6f7d1725",
  "latency": 181,
  "status": "OK",
  "result": {
    "skill_id": "s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166",
    "status": "success",
    "message": "Skill s-c0e6aaf9-8dea-4729-a958-f11b9a2e3166 deleted"
  }
}

Knowledge Base API (V3)

For all Knowledge Base operations in this section, the URI prefix is /v3/openapi/workspaces/{workspace_name}/memory/{service_id}. You must first create a knowledge base in the console to obtain the kb_id.

Upload a KB document

Uploads a document to the knowledge base. Supports two source types: LOCAL (local file URL) and OSS.

Request method

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/knowledge-bases/{kb_id}/docs

Body parameters

Parameter	Type	Required	Description	Example
type	String	Yes	The document source type. Valid values: LOCAL: local file URL OSS: OSS object.	LOCAL
doc.id	String	No	The custom ID for the local document (optional when type=LOCAL).	doc-001
doc.title	String	No	The document title (optional when type=LOCAL).	User manual
doc.file_url	String	Conditionally required	The accessible URL of the local document. Required when type=LOCAL.	https://example.com/manual.pdf
doc.oss_path	String	Conditionally required	The OSS object path. Required when type=OSS.	docs/manual.pdf
doc.oss_bucket	String	Conditionally required	The OSS bucket name. Required when type=OSS.	my-bucket
doc.oss_endpoint	String	Conditionally required	The OSS endpoint. Required when type=OSS.	oss-cn-hangzhou.aliyuncs.com

Response parameters

The response contains id (the document ID generated after a successful upload) and result.error_message (not empty on failure).

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/knowledge-bases/kb-001/docs' \
--header 'Authorization: Bearer your-API-KEY' \
--header 'Content-Type: application/json' \
--data '{
  "type": "LOCAL",
  "doc": {
    "id": "doc-001",
    "title": "User manual",
    "file_url": "https://example.com/manual.pdf"
  }
}'

Get the KB document list

Retrieves the list of documents under the knowledge base with pagination. The query parameters page_number (default 1) and page_size (default 10, maximum 100) are optional. The response result.results[] contains id, title, timestamp, and status (PROCESSING / SUCCESS / FAIL). result.total is the total count.

Request method

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/knowledge-bases/{kb_id}/docs

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/knowledge-bases/kb-001/docs?page_number=1&page_size=10' \
--header 'Authorization: Bearer your-API-KEY'

View KB document details

Retrieves the details of a knowledge base document by document ID. The response result contains the id, title, content, status, and timestamp fields.

Request method

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/knowledge-bases/{kb_id}/docs/{doc_id}

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/knowledge-bases/kb-001/docs/doc-001' \
--header 'Authorization: Bearer your-API-KEY'

Delete a KB document

Deletes a knowledge base document by document ID. The response result contains id (the ID of the deleted document) and error_message (not empty on failure).

Request method

DELETE

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/knowledge-bases/{kb_id}/docs/{doc_id}

Sample curl request

curl --location --request DELETE 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/knowledge-bases/kb-001/docs/doc-001' \
--header 'Authorization: Bearer your-API-KEY'

Service status API

Health check

Checks the health status of the Memory service. This API is under the Service status category, and its URI follows the V3 prefix (there is no health endpoint under the V4 path).

Request method

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/memory/{service_id}/health

Response parameters

Parameter	Type	Description	Example
result.status	String	The service health status. Valid values: healthy and unhealthy.	healthy

Sample curl request

curl --location 'http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/memory/agentic-memory/health' \
--header 'Authorization: Bearer your-API-KEY'

Sample response

{
  "request_id": "287d9462-3c9a-2706-780e-b49aa3702e01",
  "latency": 6,
  "status": "OK",
  "result": {
    "status": "healthy"
  }
}

Common response fields

The following fields are included in the outer layer of the response for all APIs.

Parameter	Type	Description	Example
request_id	String	The unique identifier assigned by the system to an API call.	9907b179-7bcc-2c43-21db-d3c9d777bbfe
latency	Int	The request duration, in ms.	161
status	String	The request status.	OK

Status codes

HTTP status code	Error code	Description
200	-	The request succeeded. The actual processing status of an async task must be determined from status (V3 lowercase: completed/running/pending/failed; V4 uppercase: SUCCEEDED/PENDING/FAILED).
400	InvalidParameter	The request parameters are invalid.
400	CredentialsNotFound	The authentication information is invalid (Invalid token). Check whether the API-Key in the Authorization request header is correct.
200	InternalServerError / NotFound	The resource does not exist (Memory / Skill / Task / Knowledge Base, and so on). The server wraps business-level NotFound errors in an HTTP 200 response with a code field. Determine the specific error through the code and message fields in the response body, rather than relying only on the HTTP status code.
429	RateLimitExceeded	The request frequency exceeds the limit.
500	InternalServerError	An internal server error occurred.

Sample error response

{
  "request_id": "590A7EB8-AA84-****-AF31-8C35DC965972",
  "latency": 0,
  "code": "InvalidParameter",
  "http_code": 400,
  "message": "user_id is required"
}