{
  "schema_version": 2,
  "id": "operate/iris/agent-playbook/self-managed/api-examples",
  "title": "Self-managed Agent Playbooks API examples",
  "url": "https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/api-examples/",
  "summary": "Create a playbook, mint publisher and reader agent keys, verify agent access, and hand connection details to a developer.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-11-03T15:26:57-08:00",
  "page_type": "content",
  "content_hash": "4ef8afc0fc75c640fca8c5af635ce6b555db132f3794f32395b9d50ebb37bdc4",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Create a playbook, issue publisher and reader agent keys, and verify application access with curl or the Iris command-line interface (CLI).\n\nBefore you begin, [deploy the chart and forward the APIs](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/deploy#6-verify-pods-and-health), then [load the administrative credentials](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/authentication#load-the-administrative-credentials). Keep response files private:\n\n[code example]\n\nThe local HTTP addresses use the Kubernetes port-forwards. For application deployment, give developers the data-plane endpoint your platform exposes."
    },
    {
      "id": "create-a-playbook",
      "title": "Create a playbook",
      "role": "content",
      "text": "List the embedding models configured for this deployment:\n\n[code example]\n\nCreate the playbook with one of the returned identities:\n\n[code example]\n\nPlaybook IDs start with `pb_`. Read the playbook's state:\n\n[code example]\n\nContinue when `state` is `READY`. If it is `PROVISIONING`, repeat the read. If it is `FAILED`, check service health and logs before you retry. Creating a playbook with a name already in use returns `409`.\n\nTo list playbooks, send `GET /iris/v1/agent-playbooks/playbooks`. The response holds `items` and, when more follow, a `nextCursor` to pass back as `cursor`."
    },
    {
      "id": "create-agent-keys",
      "title": "Create agent keys",
      "role": "content",
      "text": "Create a publisher grant for this playbook:\n\n[code example]\n\nUse the deployment's `tenantId` as `tenant`. Issue the key through the Identity Service:\n\n[code example]\n\nIssue a separate reader key for the same playbook:\n\n[code example]\n\nSave both tokens in your secret manager and keep their `keyId` values. The Identity Service returns a token only when it creates or rotates a key. Minting fails if the playbook doesn't exist or the grant names another tenant."
    },
    {
      "id": "verify-application-access",
      "title": "Verify application access",
      "role": "content",
      "text": "[code example]\n\nThe response reports `READY` for the playbook, its metadata and content Redis, the embedding provider, and the license."
    },
    {
      "id": "hand-off-to-a-developer",
      "title": "Hand off to a developer",
      "role": "content",
      "text": "Give the content team the data-plane endpoint, the playbook ID, and the publisher key for the [developer quickstart](https://redis.io/docs/latest/develop/ai/context-engine/agent-playbooks/quickstart). They set these variables:\n\n[code example]\n\nGive runtime agents the reader key instead, for [agent integration](https://redis.io/docs/latest/develop/ai/context-engine/agent-playbooks/agent-integration) over REST or [MCP](https://redis.io/docs/latest/develop/ai/context-engine/agent-playbooks/mcp). Remove the local key-response files after you save both tokens."
    },
    {
      "id": "use-the-iris-cli",
      "title": "Use the Iris CLI",
      "role": "content",
      "text": "The Iris CLI reads the same variables. Install it with Python 3.11 or later:\n\n[code example]\n\nCreate a playbook and mint a read-only key for it in one step, writing the connection values to `.env`:\n\n[code example]\n\n`--embedding-provider` accepts `openai` or `noop`, so the CLI can create playbooks only for a connection named `openai`. The CLI sends FAQ and skill minimum scores of `0.3` unless you pass `--faq-min-score` and `--skill-min-score`; calibrate them against your own scores. Add `--dry-run` to print the request without sending it.\n\nMint a content key with `read`, `write`, and `publish` for an existing playbook, then check every hop from the control plane to a data read:\n\n[code example]\n\nInspect a playbook with `iris agent-playbooks service show <playbook-id>`, and list, rotate, or revoke keys with `iris identity keys`. Keys the CLI mints expire after 90 days unless you pass `--expires`.\n\nFor retrieval settings, see [Playbook settings](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration#playbook-settings)."
    }
  ],
  "examples": [
    {
      "id": "overview-ex0",
      "language": "bash",
      "code": "umask 077",
      "section_id": "overview"
    },
    {
      "id": "create-a-playbook-ex0",
      "language": "bash",
      "code": "curl --fail-with-body -sS \\\n  \"$IRIS_AGENT_PLAYBOOKS_SERVICE_URL/iris/v1/agent-playbooks/models\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_PLAYBOOKS_SERVICE_TOKEN\" \\\n  | jq '.items[] | select(.purpose == \"EMBEDDING\")'",
      "section_id": "create-a-playbook"
    },
    {
      "id": "create-a-playbook-ex1",
      "language": "bash",
      "code": "jq -n \\\n  --arg provider '<provider>' \\\n  --arg model '<model>' \\\n  --argjson dimensions '<dimensions>' \\\n  '{name: \"support\", embedding: {provider: $provider, model: $model, dimensions: $dimensions}}' \\\n  > playbook-request.json\n\ncurl --fail-with-body -sS \\\n  -X POST \"$IRIS_AGENT_PLAYBOOKS_SERVICE_URL/iris/v1/agent-playbooks/playbooks\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_PLAYBOOKS_SERVICE_TOKEN\" \\\n  -H 'Content-Type: application/json' \\\n  --data-binary @playbook-request.json > playbook.json\nexport IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID=\"$(jq -er '.playbookId' playbook.json)\"",
      "section_id": "create-a-playbook"
    },
    {
      "id": "create-a-playbook-ex2",
      "language": "bash",
      "code": "curl --fail-with-body -sS \\\n  \"$IRIS_AGENT_PLAYBOOKS_SERVICE_URL/iris/v1/agent-playbooks/playbooks/$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_PLAYBOOKS_SERVICE_TOKEN\" \\\n  | jq '{playbookId, state, embedding, discovery}'",
      "section_id": "create-a-playbook"
    },
    {
      "id": "create-agent-keys-ex0",
      "language": "bash",
      "code": "jq -n --arg id \"$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID\" '{\n  name: \"support-publisher\",\n  grants: [{\n    tenant: \"default\",\n    product: \"playbook\",\n    resourceType: \"playbook\",\n    resourceId: $id,\n    actions: [\"write\", \"publish\"]\n  }]\n}' > publisher-grant.json",
      "section_id": "create-agent-keys"
    },
    {
      "id": "create-agent-keys-ex1",
      "language": "bash",
      "code": "curl --fail-with-body -sS \\\n  -X POST \"$IRIS_IDENTITY_URL/v1/api-keys\" \\\n  -H \"Authorization: Bearer $IRIS_IDENTITY_TOKEN\" \\\n  -H 'Content-Type: application/json' \\\n  --data-binary @publisher-grant.json > publisher-key.json\nexport IRIS_AGENT_PLAYBOOKS_API_KEY=\"$(jq -er '.token' publisher-key.json)\"",
      "section_id": "create-agent-keys"
    },
    {
      "id": "create-agent-keys-ex2",
      "language": "bash",
      "code": "jq '.name = \"support-reader\" | .grants[0].actions = [\"read\"]' publisher-grant.json \\\n  | curl --fail-with-body -sS \\\n    -X POST \"$IRIS_IDENTITY_URL/v1/api-keys\" \\\n    -H \"Authorization: Bearer $IRIS_IDENTITY_TOKEN\" \\\n    -H 'Content-Type: application/json' \\\n    --data-binary @- > reader-key.json",
      "section_id": "create-agent-keys"
    },
    {
      "id": "verify-application-access-ex0",
      "language": "bash",
      "code": "curl --fail-with-body -sS \\\n  \"$IRIS_AGENT_PLAYBOOKS_URL/iris/data/v1/agent-playbooks/playbooks/$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID/health\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_PLAYBOOKS_API_KEY\"",
      "section_id": "verify-application-access"
    },
    {
      "id": "hand-off-to-a-developer-ex0",
      "language": "dotenv",
      "code": "IRIS_AGENT_PLAYBOOKS_URL='<data-plane-endpoint>'\nIRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID='<playbook-id>'\nIRIS_AGENT_PLAYBOOKS_API_KEY='<playbook-api-key>'",
      "section_id": "hand-off-to-a-developer"
    },
    {
      "id": "use-the-iris-cli-ex0",
      "language": "bash",
      "code": "python -m pip install 'redis-iris>=1.0.0'",
      "section_id": "use-the-iris-cli"
    },
    {
      "id": "use-the-iris-cli-ex1",
      "language": "bash",
      "code": "iris agent-playbooks service create --name support \\\n  --embedding-provider openai \\\n  --embedding-model '<model>' \\\n  --embedding-dimensions '<dimensions>' \\\n  --key-actions read \\\n  --write-env .env",
      "section_id": "use-the-iris-cli"
    },
    {
      "id": "use-the-iris-cli-ex2",
      "language": "bash",
      "code": "iris agent-playbooks service key \"$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID\" --role content --write .env\niris agent-playbooks service check \"$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID\" --env-file .env",
      "section_id": "use-the-iris-cli"
    }
  ]
}