Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Make an API Call with the Agent Memory API

  • how-to
How to make an API call with the Agent Memory API on a self-managed Agent Memory server.

This page is for self-managed Agent Memory.

Use the Agent Memory API to store and retrieve memory for your AI agents on your Agent Memory server.

Prerequisites

To make an API call with the Agent Memory API, you need:

Make an API Call

You can use a client such as curl to make an API call with the Agent Memory API.

To make an API call with the Agent Memory API:

  1. Use the hostname and port of your Agent Memory server as the base URL:

    http://<HOST>:<PORT>

  2. If your Agent Memory server uses authentication, pass the access token as a Bearer token using the HTTP Authorization header.

  3. If the endpoint requires a request body, pass it in JSON format.

Alternatively, you can use a client such as Insomnia or Postman to explore the details of the REST API. The Agent Memory API uses an OpenAPI v3 specification. To download the Agent Memory API specification, go to the Agent Memory API Reference and click Download.

Examples

The following examples show how to store memory with the Agent Memory API. Run them in order, because each example uses the user or session created in the previous one:

  1. Create a User

  2. Create a Session

  3. Add Memory Blocks

If your Agent Memory server does not use authentication, remove the Authorization header from each example.

Create a User

The following POST request creates a user. You choose the user_id, which must be unique.

HTTP Request
curl "$BASE_URL/users" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
  "user_id": "user_123",
  "name": "John Doe"
}'

The response is a JSON object similar to the following:

HTTP Response
{
  "id": "user_123",
  "name": "John Doe",
  "sessions": [],
  "metadata": {}
}

The response includes the user ID. You can use the user ID for any further API calls in which {USER_ID} is a path parameter.

Create a Session

The following POST request creates a session for the user. You choose the session_id, which must be unique for the user.

HTTP Request
curl "$BASE_URL/users/user_123/sessions" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
  "session_id": "session_456"
}'

The response is a JSON object similar to the following:

HTTP Response
{
  "user_id": "user_123",
  "session_id": "session_456",
  "start_time": "2026-09-24 14:30:00.123456",
  "end_time": null,
  "annotations": {},
  "metadata": {},
  "blocks_ttl": null
}

The response includes the session ID. You can use the session ID for any further API calls in which {SESSION_ID} is a path parameter.

Add Memory Blocks

The following POST request adds 2 facts to the session as memory blocks.

The request sets async_processing to false, so Agent Memory processes the memory blocks before it returns a response. You can then search the memory blocks immediately.

HTTP Request
curl "$BASE_URL/users/user_123/sessions/session_456/memory" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
  "facts": [
    "User prefers email notifications",
    "User is allergic to peanuts"
  ],
  "async_processing": false
}'

The response is a JSON object similar to the following:

HTTP Response
{
  "message": "Successfully added 2 memory block(s).",
  "accepted_count": 2,
  "block_ids": [
    "<BLOCK_ID_1>",
    "<BLOCK_ID_2>"
  ],
  "rejected_count": 0,
  "rejected_details": null
}

The response includes the ID of each memory block that Agent Memory added.

Next Steps