Agentic Memory REST API Reference

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 public network or VPC. For more information, see Obtain a 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

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), and you can use the Check event status API to obtain the processing result. The system automatically searches existing memories for deduplication and determines whether to create or update.

Request method

POST

URL

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

Body parameters

Response parameters

cURL request example

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 coffee, please recommend some"},
    {"role": "assistant", "content": "Here are some Americano recommendations..."}
  ],
  "user_id": "user_123",
  "metadata": {"source": "example"}
}'

Response example

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

Check event status

Queries the async event processing status and the list of generated Memories for a Store memory operation.

Request method

GET

URL

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

Path parameters

Response parameters

cURL request example

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'

Response example

{
  "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 Memory 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

{
  "AND": [
    {
      "user_id": "user_123"
    },
    {
      "agent_id": "agent_123"
    }
  ]
}

Response parameters

cURL request example

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
}'

Response example

{
  "results": [
      {
        "id": "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04",
        "memory": "The assistant recommended 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 a single Memory by Memory ID.

Request method

GET

URL

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

Path parameters

Response parameters

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

cURL request example

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'

Response example

{
  "id": "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04",
  "memory": "The assistant recommended 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

cURL request example

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 latte to the user",
  "metadata": {"category": "updated"}
}'

Response example

{
  "id": "m-877edf7b-cb5a-4f43-bc6b-f8fa022a3a04",
  "text": "The assistant recommended 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 message field in the response indicates the deletion result.

Request method

DELETE

URL

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

cURL request example

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'

Response example

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

Extract and store skill

Intelligently extracts reusable skills (Skill) from multi-turn conversations and stores them. Processing is asynchronous. The API returns a task ID, and you can use the Check skill task status API to obtain the result.

Request method

POST

URL

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

Body parameters

cURL request example

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 login failure message across platforms"},
    {"role": "assistant", "content": "Standardize the login failure message to "Login failed, please try again" across Android, iOS, and Web"}
  ],
  "user_id": "user_123"
}'

Response example

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

Upload skill (ZIP import)

Batch uploads Skills through a ZIP package. Returns the number of successfully imported Skills and a metadata list.

Request method

POST

URL

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

Body parameters

Response parameters

cURL request example

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"
}'

Response example

{
  "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 via 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"
      }
    ]
  }
}

Check skill task status

Queries the async task processing status and the list of generated Skill IDs for an Extract and store skill operation.

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.

cURL request example

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'

Response example

{
  "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

cURL request example

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
}'

Response example

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

Get skill

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

Request method

GET

URL

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

cURL request example

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'

Response example

{
  "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. The user_id is required in the body. Other fields (name, version, files, agent_id, description, tags) are provided as needed. The response structure is the same as that of Get skill.

Request method

PUT

URL

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

cURL request example

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"
}'

Response example

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

Delete skill

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

Request method

DELETE

URL

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

cURL request example

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'

Response example

{
  "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"
  }
}

Upload KB document

Uploads a document to the knowledge base. Two source types are supported: 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

Response parameters

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

cURL request example

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"
  }
}'

List KB documents

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

Request method

GET

URL

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

cURL request example

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'

Get KB document details

Retrieves knowledge base document details 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}

cURL request example

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 KB document

Deletes a knowledge base document by document ID. The response result contains id (the deleted document ID) 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}

cURL request example

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'

Health check

Checks the health status of the Memory service. This API is under the Service status category and uses the V3 prefix (no health endpoint exists under the V4 path).

Request method

GET

URL

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

Response parameters

cURL request example

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

Response example

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

Error response example

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