Self-managed API examples

Use curl examples with the Redis Agent Memory self-managed Control Plane and Data Plane APIs.

Redis Agent Memory self-managed is currently in private preview and subject to change. A license key is required to deploy. Contact your Redis representative or contact sales.

These examples show self-managed Control Plane, Identity Service, and Data Plane requests.

They assume either an auth-disabled private Data Plane or agent-key auth configured as described in Authentication and authorization.

For the complete shared Data Plane schema, see the Redis Agent Memory API. For the self-managed admin schema, see the Control Plane API reference.

Control Plane API examples

Set variables:

CP_URL="http://localhost:9100"
RAM_ADMIN_TOKEN="<admin-token>"

List stores:

curl -sS "$CP_URL/v1/stores" \
  -H "Authorization: Bearer $RAM_ADMIN_TOKEN"

Create a store:

curl -sS -X POST "$CP_URL/v1/stores" \
  -H "Authorization: Bearer $RAM_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-store"
  }'

Response:

{
  "storeId": "<store-id>"
}

List the built-in sensitive-data detectors a store may select:

curl -sS "$CP_URL/v1/detectors" \
  -H "Authorization: Bearer $RAM_ADMIN_TOKEN"

Response:

{
  "catalogVersion": "1.0.0",
  "detectors": [
    {
      "id": "credit-card",
      "name": "Credit card number",
      "description": "Payment card numbers, covering Visa, Mastercard, American Express, Discover, JCB, Diners Club and UnionPay. Maestro is not covered. Digits may be separated by spaces or hyphens."
    }
  ]
}

Read detector IDs from this endpoint rather than copying them from documentation. The catalog is compiled into the server, so it is never empty, and catalogVersion identifies the generation a result came from.

Create a store with sensitive-data exclusions:

curl -sS -X POST "$CP_URL/v1/stores" \
  -H "Authorization: Bearer $RAM_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-store",
    "longTermMemoryExclusions": {
      "enabled": true,
      "builtInDetectors": {
        "enabled": true,
        "detectors": [
          { "id": "credit-card", "enabled": true, "action": "drop" },
          { "id": "ip-address", "enabled": true, "action": "redact" }
        ]
      },
      "customDetectors": {
        "enabled": true,
        "detectors": [
          {
            "name": "internal-case-reference",
            "enabled": true,
            "action": "redact",
            "matcher": {
              "kind": "regex",
              "regex": { "pattern": "CASE-REF-[0-9]{6}" }
            }
          }
        ]
      },
      "semantic": {
        "enabled": true,
        "prompt": "Never keep a customer's payment card number in long-term memory."
      }
    }
  }'

Exclusions fields:

Field	Notes
`enabled`	Required. Gates all three mechanisms. Turning it off stops enforcement without discarding what you configured.
`builtInDetectors.enabled`	Required.
`builtInDetectors.detectors[].id`	Required. A detector ID from `/v1/detectors`.
`customDetectors.enabled`	Required.
`customDetectors.detectors[].name`	Required. 1-64 characters, starting with a letter, followed by letters, digits, underscores, or dashes. Unique within the store, and not a built-in detector ID.
`detectors[].enabled`	Required on every built-in and custom detector.
`matcher.kind`	Required. Use `regex`.
`matcher.regex.pattern`	Required when `kind` is `regex`. 1-512 characters, using RE2 syntax, so lookaround is unavailable. Rejected if it does not compile, or if it can match without consuming text.
`action`	Optional on any detector. Use `redact` to replace the matched text or `drop` to discard the memory. Defaults to `redact`.
`semantic.enabled`	Required.
`semantic.prompt`	Required when `semantic.enabled` is `true`. Up to 2,000 characters.

A store may define at most 32 custom detectors. Update an existing store's policy by sending longTermMemoryExclusions on a store update.

For what each mechanism does, how a match is handled, and which memory paths exclusions apply to, see exclude sensitive data from automatic extraction.

Identity Service API examples

Manage agent keys with the Identity Service, using the Identity Service control token.

Set variables:

IDS_URL="http://localhost:9200"
IDS_CONTROL_TOKEN="<identity-service-control-token>"

Mint an agent key:

curl -sS -X POST "$IDS_URL/v1/api-keys" \
  -H "Authorization: Bearer $IDS_CONTROL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent-key",
    "grants": [
      {
        "tenant": "<your-tenant-id>",
        "product": "memory",
        "resourceType": "mem-store",
        "resourceId": "<store-id>",
        "actions": ["read", "write"]
      }
    ]
  }'

Response:

{
  "keyId": "0123456789abcdef0123456789abcdef",
  "token": "<agent-key>",
  "createdAt": 1780000000
}

Agent-key fields:

Field	Notes
Endpoint	Use `/v1/api-keys`.
`name`	Required.
`grants`	Required.
`tenant`	Your tenant ID. Use the same tenant on every grant of a key. Any string is accepted. Use `1` if you manage stores with the Control Plane admin token.
`product`	Use `memory`.
`resourceType`	Use `mem-store`.
`resourceId`	Set to the store ID.
`actions`	Use `read`, `write`, or both.
`expiresAt`	Optional. Unix seconds after which the key stops authenticating. `0` or omitted means never.
Token	Returned only when you mint or rotate a key. Store it immediately.

List agent keys:

curl -sS "$IDS_URL/v1/api-keys" \
  -H "Authorization: Bearer $IDS_CONTROL_TOKEN"

Get one agent key:

curl -sS "$IDS_URL/v1/api-keys/<key-id>" \
  -H "Authorization: Bearer $IDS_CONTROL_TOKEN"

Update an agent key's grants:

curl -sS -X PATCH "$IDS_URL/v1/api-keys/<key-id>" \
  -H "Authorization: Bearer $IDS_CONTROL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "grants": [
      {
        "tenant": "<your-tenant-id>",
        "product": "memory",
        "resourceType": "mem-store",
        "resourceId": "<store-id>",
        "actions": ["read", "write"]
      }
    ]
  }'

Rotate an agent key:

curl -sS -X POST "$IDS_URL/v1/api-keys/<key-id>/rotate?graceSeconds=3600" \
  -H "Authorization: Bearer $IDS_CONTROL_TOKEN"

Response:

{
  "createdAt": 1780000000,
  "keyId": "fedcba9876543210fedcba9876543210",
  "oldExpiresAt": 1780003600,
  "token": "<new-agent-key>"
}

Rotation returns a new keyId with the new token. Use the new keyId for later updates, rotations, and revocations. The old key stays valid for graceSeconds, which defaults to 3600 and has a chart maximum of 604800 (identityService.apiKeys.maxRotateGraceSeconds). oldExpiresAt is when the old key stops working. Revoking the old keyId ends its grace period early.

Revoke an agent key:

curl -sS -X DELETE "$IDS_URL/v1/api-keys/<key-id>" \
  -H "Authorization: Bearer $IDS_CONTROL_TOKEN"

A revoked key stops working within up to 5 minutes.

Data Plane API examples

Set variables:

DP_URL="http://localhost:9000"
STORE_ID="<store-id>"
RAM_AGENT_KEY="<agent-key>"

For auth-disabled deployments, omit the Authorization header and rely on the deployment's hosting controls.

Write a session event

curl -sS -X POST "$DP_URL/v1/stores/$STORE_ID/session-memory/events" \
  -H "Authorization: Bearer $RAM_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-001",
    "actorId": "user-001",
    "role": "USER",
    "content": [
      {
        "text": "What is the capital of France?"
      }
    ],
    "createdAt": "2026-06-25T18:00:00Z"
  }'

Request body fields:

Field	Notes
`actorId`	Required.
`role`	Required. Use `USER`, `ASSISTANT`, or `SYSTEM`.
`content`	Required. For text, use a content object such as `{"text": "..."}`.
`createdAt`	Required. Use an RFC 3339 timestamp, for example `2026-06-25T18:00:00Z`.
`sessionId`	Optional. If omitted, Redis Agent Memory generates one.

Read session memory

curl -sS "$DP_URL/v1/stores/$STORE_ID/session-memory/session-001" \
  -H "Authorization: Bearer $RAM_AGENT_KEY"

List sessions

List sessions for a specific owner:

curl -sS "$DP_URL/v1/stores/$STORE_ID/session-memory?filterOwnerId=user-001" \
  -H "Authorization: Bearer $RAM_AGENT_KEY"

List all sessions:

curl -sS "$DP_URL/v1/stores/$STORE_ID/session-memory?includeAll=true" \
  -H "Authorization: Bearer $RAM_AGENT_KEY"

filterOwnerId and includeAll are mutually exclusive.

Create long-term memories directly

curl -sS -X POST "$DP_URL/v1/stores/$STORE_ID/long-term-memory" \
  -H "Authorization: Bearer $RAM_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {
        "id": "pref-email-updates",
        "text": "User prefers email updates.",
        "memoryType": "semantic",
        "ownerId": "user-001",
        "namespace": "preferences",
        "topics": ["communications"]
      }
    ]
  }'

Search long-term memory

curl -sS -X POST "$DP_URL/v1/stores/$STORE_ID/long-term-memory/search" \
  -H "Authorization: Bearer $RAM_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "How should we contact this user?",
    "filter": {
      "ownerId": {
        "eq": "user-001"
      }
    },
    "limit": 5
  }'

	Products	Version
	Develop with Redis Clients, data types, programmability, and Redis for AI. RedisVL is listed separately.
	Libraries and tools Client libraries, observability, and cloud integrations. Redis Data Integration is listed separately.
	RedisVL
	Redis Software
	Redis Cloud
	Redis for Kubernetes
	Redis Open Source
	Redis Iris context engine
	Redis Feature Form
	Redis Insight
	Redis Data Integration
	Glossary
	Command reference

Self-managed API examples

Control Plane API examples

Identity Service API examples

Data Plane API examples

Write a session event

Read session memory

List sessions

Create long-term memories directly

Search long-term memory

On this page