{
  "schema_version": 2,
  "id": "operate/iris/agent-memory/self-managed/api-examples",
  "title": "Self-managed API examples",
  "url": "https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/api-examples/",
  "summary": "Use curl examples with the Redis Agent Memory self-managed Control Plane and Data Plane APIs.",
  "aliases": [
    "/develop/ai/context-engine/agent-memory/self-managed/api-examples/"
  ],
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-10-06T11:56:03+03:00",
  "page_type": "content",
  "content_hash": "5f4b37b9e6152ab90401828d724d27dfaa377b10c3eb0b8443694ad0d95b1804",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "These examples show self-managed Control Plane, Identity Service, and Data Plane requests.\n\nThey assume either an auth-disabled private Data Plane or agent-key auth\nconfigured as described in [Authentication and authorization](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/authentication).\n\nFor the complete shared Data Plane schema, see the\n[Redis Agent Memory API](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/api-reference).\nFor the self-managed admin schema, see the\n[Control Plane API reference](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/control-plane-api-reference)."
    },
    {
      "id": "control-plane-api-examples",
      "title": "Control Plane API examples",
      "role": "content",
      "text": "Set variables:\n\n[code example]\n\nList stores:\n\n[code example]\n\nCreate a store:\n\n[code example]\n\nResponse:\n\n[code example]\n\nList the built-in sensitive-data detectors a store may select:\n\n[code example]\n\nResponse:\n\n[code example]\n\nRead 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.\n\nCreate a store with sensitive-data exclusions:\n\n[code example]\n\nExclusions fields:\n\n| Field | Notes |\n| ----- | ----- |\n| `enabled` | Required. Gates all three mechanisms. Turning it off stops enforcement without discarding what you configured. |\n| `builtInDetectors.enabled` | Required. |\n| `builtInDetectors.detectors[].id` | Required. A detector ID from `/v1/detectors`. |\n| `customDetectors.enabled` | Required. |\n| `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. |\n| `detectors[].enabled` | Required on every built-in and custom detector. |\n| `matcher.kind` | Required. Use `regex`. |\n| `matcher.regex.pattern` | Required when `kind` is `regex`. 1-512 characters, using [RE2 syntax](https://github.com/google/re2/wiki/Syntax), so lookaround is unavailable. Rejected if it does not compile, or if it can match without consuming text. |\n| `action` | Optional on any detector. Use `redact` to replace the matched text or `drop` to discard the memory. Defaults to `redact`. |\n| `semantic.enabled` | Required. |\n| `semantic.prompt` | Required when `semantic.enabled` is `true`. Up to 2,000 characters. |\n\nA store may define at most 32 custom detectors. Update an existing store's policy by sending `longTermMemoryExclusions` on a store update.\n\nFor what each mechanism does, how a match is handled, and which memory paths exclusions apply to, see [exclude sensitive data from automatic extraction](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/developer-guide#exclude-sensitive-data-from-automatic-extraction)."
    },
    {
      "id": "identity-service-api-examples",
      "title": "Identity Service API examples",
      "role": "content",
      "text": "Manage agent keys with the Identity Service, using the Identity Service control token.\n\nSet variables:\n\n[code example]\n\nMint an agent key:\n\n[code example]\n\nResponse:\n\n[code example]\n\nAgent-key fields:\n\n| Field | Notes |\n| ----- | ----- |\n| Endpoint | Use `/v1/api-keys`. |\n| `name` | Required. |\n| `grants` | Required. |\n| `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. |\n| `product` | Use `memory`. |\n| `resourceType` | Use `mem-store`. |\n| `resourceId` | Set to the store ID. |\n| `actions` | Use `read`, `write`, or both. |\n| `expiresAt` | Optional. Unix seconds after which the key stops authenticating. `0` or omitted means never. |\n| Token | Returned only when you mint or rotate a key. Store it immediately. |\n\nList agent keys:\n\n[code example]\n\nGet one agent key:\n\n[code example]\n\nUpdate an agent key's grants:\n\n[code example]\n\nRotate an agent key:\n\n[code example]\n\nResponse:\n\n[code example]\n\nRotation returns a new `keyId` with the new token. Use the new `keyId` for later updates,\nrotations, and revocations. The old key stays valid for `graceSeconds`, which defaults to 3600 and\nhas a chart maximum of 604800 (`identityService.apiKeys.maxRotateGraceSeconds`). `oldExpiresAt` is\nwhen the old key stops working. Revoking the old `keyId` ends its grace period early.\n\nRevoke an agent key:\n\n[code example]\n\nA revoked key stops working within up to 5 minutes."
    },
    {
      "id": "data-plane-api-examples",
      "title": "Data Plane API examples",
      "role": "content",
      "text": "Set variables:\n\n[code example]\n\nFor auth-disabled deployments, omit the `Authorization` header and rely on the\ndeployment's hosting controls."
    },
    {
      "id": "write-a-session-event",
      "title": "Write a session event",
      "role": "content",
      "text": "[code example]\n\nRequest body fields:\n\n| Field | Notes |\n| ----- | ----- |\n| `actorId` | Required. |\n| `role` | Required. Use `USER`, `ASSISTANT`, or `SYSTEM`. |\n| `content` | Required. For text, use a content object such as `{\"text\": \"...\"}`. |\n| `createdAt` | Required. Use an RFC 3339 timestamp, for example `2026-06-25T18:00:00Z`. |\n| `sessionId` | Optional. If omitted, Redis Agent Memory generates one. |"
    },
    {
      "id": "read-session-memory",
      "title": "Read session memory",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "list-sessions",
      "title": "List sessions",
      "role": "content",
      "text": "List sessions for a specific owner:\n\n[code example]\n\nList all sessions:\n\n[code example]\n\n`filterOwnerId` and `includeAll` are mutually exclusive."
    },
    {
      "id": "create-long-term-memories-directly",
      "title": "Create long-term memories directly",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "search-long-term-memory",
      "title": "Search long-term memory",
      "role": "content",
      "text": "[code example]"
    }
  ],
  "examples": [
    {
      "id": "control-plane-api-examples-ex0",
      "language": "bash",
      "code": "CP_URL=\"http://localhost:9100\"\nRAM_ADMIN_TOKEN=\"<admin-token>\"",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex1",
      "language": "bash",
      "code": "curl -sS \"$CP_URL/v1/stores\" \\\n  -H \"Authorization: Bearer $RAM_ADMIN_TOKEN\"",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex2",
      "language": "bash",
      "code": "curl -sS -X POST \"$CP_URL/v1/stores\" \\\n  -H \"Authorization: Bearer $RAM_ADMIN_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"my-store\"\n  }'",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex3",
      "language": "json",
      "code": "{\n  \"storeId\": \"<store-id>\"\n}",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex4",
      "language": "bash",
      "code": "curl -sS \"$CP_URL/v1/detectors\" \\\n  -H \"Authorization: Bearer $RAM_ADMIN_TOKEN\"",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex5",
      "language": "json",
      "code": "{\n  \"catalogVersion\": \"1.0.0\",\n  \"detectors\": [\n    {\n      \"id\": \"credit-card\",\n      \"name\": \"Credit card number\",\n      \"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.\"\n    }\n  ]\n}",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex6",
      "language": "bash",
      "code": "curl -sS -X POST \"$CP_URL/v1/stores\" \\\n  -H \"Authorization: Bearer $RAM_ADMIN_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"my-store\",\n    \"longTermMemoryExclusions\": {\n      \"enabled\": true,\n      \"builtInDetectors\": {\n        \"enabled\": true,\n        \"detectors\": [\n          { \"id\": \"credit-card\", \"enabled\": true, \"action\": \"drop\" },\n          { \"id\": \"ip-address\", \"enabled\": true, \"action\": \"redact\" }\n        ]\n      },\n      \"customDetectors\": {\n        \"enabled\": true,\n        \"detectors\": [\n          {\n            \"name\": \"internal-case-reference\",\n            \"enabled\": true,\n            \"action\": \"redact\",\n            \"matcher\": {\n              \"kind\": \"regex\",\n              \"regex\": { \"pattern\": \"CASE-REF-[0-9]{6}\" }\n            }\n          }\n        ]\n      },\n      \"semantic\": {\n        \"enabled\": true,\n        \"prompt\": \"Never keep a customer's payment card number in long-term memory.\"\n      }\n    }\n  }'",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex0",
      "language": "bash",
      "code": "IDS_URL=\"http://localhost:9200\"\nIDS_CONTROL_TOKEN=\"<identity-service-control-token>\"",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex1",
      "language": "bash",
      "code": "curl -sS -X POST \"$IDS_URL/v1/api-keys\" \\\n  -H \"Authorization: Bearer $IDS_CONTROL_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"my-agent-key\",\n    \"grants\": [\n      {\n        \"tenant\": \"<your-tenant-id>\",\n        \"product\": \"memory\",\n        \"resourceType\": \"mem-store\",\n        \"resourceId\": \"<store-id>\",\n        \"actions\": [\"read\", \"write\"]\n      }\n    ]\n  }'",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex2",
      "language": "json",
      "code": "{\n  \"keyId\": \"0123456789abcdef0123456789abcdef\",\n  \"token\": \"<agent-key>\",\n  \"createdAt\": 1780000000\n}",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex3",
      "language": "bash",
      "code": "curl -sS \"$IDS_URL/v1/api-keys\" \\\n  -H \"Authorization: Bearer $IDS_CONTROL_TOKEN\"",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex4",
      "language": "bash",
      "code": "curl -sS \"$IDS_URL/v1/api-keys/<key-id>\" \\\n  -H \"Authorization: Bearer $IDS_CONTROL_TOKEN\"",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex5",
      "language": "bash",
      "code": "curl -sS -X PATCH \"$IDS_URL/v1/api-keys/<key-id>\" \\\n  -H \"Authorization: Bearer $IDS_CONTROL_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"grants\": [\n      {\n        \"tenant\": \"<your-tenant-id>\",\n        \"product\": \"memory\",\n        \"resourceType\": \"mem-store\",\n        \"resourceId\": \"<store-id>\",\n        \"actions\": [\"read\", \"write\"]\n      }\n    ]\n  }'",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex6",
      "language": "bash",
      "code": "curl -sS -X POST \"$IDS_URL/v1/api-keys/<key-id>/rotate?graceSeconds=3600\" \\\n  -H \"Authorization: Bearer $IDS_CONTROL_TOKEN\"",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex7",
      "language": "json",
      "code": "{\n  \"createdAt\": 1780000000,\n  \"keyId\": \"fedcba9876543210fedcba9876543210\",\n  \"oldExpiresAt\": 1780003600,\n  \"token\": \"<new-agent-key>\"\n}",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex8",
      "language": "bash",
      "code": "curl -sS -X DELETE \"$IDS_URL/v1/api-keys/<key-id>\" \\\n  -H \"Authorization: Bearer $IDS_CONTROL_TOKEN\"",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "data-plane-api-examples-ex0",
      "language": "bash",
      "code": "DP_URL=\"http://localhost:9000\"\nSTORE_ID=\"<store-id>\"\nRAM_AGENT_KEY=\"<agent-key>\"",
      "section_id": "data-plane-api-examples"
    },
    {
      "id": "write-a-session-event-ex0",
      "language": "bash",
      "code": "curl -sS -X POST \"$DP_URL/v1/stores/$STORE_ID/session-memory/events\" \\\n  -H \"Authorization: Bearer $RAM_AGENT_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"sessionId\": \"session-001\",\n    \"actorId\": \"user-001\",\n    \"role\": \"USER\",\n    \"content\": [\n      {\n        \"text\": \"What is the capital of France?\"\n      }\n    ],\n    \"createdAt\": \"2026-06-25T18:00:00Z\"\n  }'",
      "section_id": "write-a-session-event"
    },
    {
      "id": "read-session-memory-ex0",
      "language": "bash",
      "code": "curl -sS \"$DP_URL/v1/stores/$STORE_ID/session-memory/session-001\" \\\n  -H \"Authorization: Bearer $RAM_AGENT_KEY\"",
      "section_id": "read-session-memory"
    },
    {
      "id": "list-sessions-ex0",
      "language": "bash",
      "code": "curl -sS \"$DP_URL/v1/stores/$STORE_ID/session-memory?filterOwnerId=user-001\" \\\n  -H \"Authorization: Bearer $RAM_AGENT_KEY\"",
      "section_id": "list-sessions"
    },
    {
      "id": "list-sessions-ex1",
      "language": "bash",
      "code": "curl -sS \"$DP_URL/v1/stores/$STORE_ID/session-memory?includeAll=true\" \\\n  -H \"Authorization: Bearer $RAM_AGENT_KEY\"",
      "section_id": "list-sessions"
    },
    {
      "id": "create-long-term-memories-directly-ex0",
      "language": "bash",
      "code": "curl -sS -X POST \"$DP_URL/v1/stores/$STORE_ID/long-term-memory\" \\\n  -H \"Authorization: Bearer $RAM_AGENT_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"memories\": [\n      {\n        \"id\": \"pref-email-updates\",\n        \"text\": \"User prefers email updates.\",\n        \"memoryType\": \"semantic\",\n        \"ownerId\": \"user-001\",\n        \"namespace\": \"preferences\",\n        \"topics\": [\"communications\"]\n      }\n    ]\n  }'",
      "section_id": "create-long-term-memories-directly"
    },
    {
      "id": "search-long-term-memory-ex0",
      "language": "bash",
      "code": "curl -sS -X POST \"$DP_URL/v1/stores/$STORE_ID/long-term-memory/search\" \\\n  -H \"Authorization: Bearer $RAM_AGENT_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"text\": \"How should we contact this user?\",\n    \"filter\": {\n      \"ownerId\": {\n        \"eq\": \"user-001\"\n      }\n    },\n    \"limit\": 5\n  }'",
      "section_id": "search-long-term-memory"
    }
  ]
}