Overview

Service address, protocol, request format, and response structure

Through the Memory API, you can programmatically write memories, search memories, and manage profile templates. All endpoints are served via the workspace-dedicated domain.

Service address

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/

{WorkspaceId} is your workspace ID, in the format llm-xxxxxxxxxxxx. On the Workspace Management page, copy the value in the API Host column to get the domain that contains your workspace ID. See Get the workspace-dedicated domain. The workspace-dedicated domain accepts only API keys that belong to the same workspace.

All endpoints use the same base URL. Append the path shown on each API page to the base URL. For example, /add corresponds to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/add.

When you use the Python SDK (agentscope-runtime), set the MEMORY_SERVICE_ENDPOINT environment variable to the base URL (without a trailing /). The SDK sends requests to this address:

export MEMORY_SERVICE_ENDPOINT="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory"

Protocol

• All endpoints use HTTPS only
• Request and response bodies are JSON in UTF-8
• Write and search use POST; list uses GET; update uses PATCH; delete uses DELETE

Common headers

Header	Required	Description
Authorization	Yes	Bearer $DASHSCOPE_API_KEY, see Authentication
Content-Type	Only for endpoints with a request body	application/json

Response format

The only common field in successful responses is request_id. Other business fields vary by API. See the corresponding API page for details.

Success:

{
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Error:

{
  "code": "InvalidParameter",
  "message": "user_id is required",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Provide request_id when contacting support for faster resolution. See Error codes.

Pagination

List endpoints support pagination:

Parameter	Description
page_size	Page size
page_num	Page number, starting from 1