# Manage intents and examples ```json metadata { "schema_version": 2, "title": "Manage intents and examples", "description": "Create, update, replace, list, and delete intents and their example phrasings.", "categories": ["docs","develop","ai"], "tableOfContents": {"sections":[{"id":"create-or-replace-an-intent","title":"Create or replace an intent"},{"id":"add-several-intents","title":"Add several intents"},{"id":"read-and-list-intents","title":"Read and list intents"},{"id":"update-an-intents-configuration","title":"Update an intent's configuration"},{"id":"avoid-overwriting-concurrent-changes","title":"Avoid overwriting concurrent changes"},{"id":"manage-examples","title":"Manage examples"},{"id":"delete-an-intent","title":"Delete an intent"},{"id":"clear-a-router","title":"Clear a Router"},{"id":"write-good-examples","title":"Write good examples"}]} , "codeExamples": [{"codetabsId":"iris_intent_router_intents-stepintent-upsert","difficulty":"beginner","id":"intent-upsert","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-stepintent-upsert"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-stepintent-upsert"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-stepintent-upsert"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-stepintent-upsert"}]},{"codetabsId":"iris_intent_router_intents-stepintents-bulk","difficulty":"beginner","id":"intents-bulk","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-stepintents-bulk"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-stepintents-bulk"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-stepintents-bulk"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-stepintents-bulk"}]},{"codetabsId":"iris_intent_router_intents-stepintents-list","difficulty":"beginner","id":"intents-list","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-stepintents-list"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-stepintents-list"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-stepintents-list"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-stepintents-list"}]},{"codetabsId":"iris_intent_router_intents-stepintent-patch","difficulty":"beginner","id":"intent-patch","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-stepintent-patch"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-stepintent-patch"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-stepintent-patch"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-stepintent-patch"}]},{"codetabsId":"iris_intent_router_intents-stepintent-conditional","difficulty":"beginner","id":"intent-conditional","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-stepintent-conditional"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-stepintent-conditional"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-stepintent-conditional"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-stepintent-conditional"}]},{"codetabsId":"iris_intent_router_intents-stepexamples-add","difficulty":"beginner","id":"examples-add","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-stepexamples-add"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-stepexamples-add"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-stepexamples-add"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-stepexamples-add"}]},{"codetabsId":"iris_intent_router_intents-stepexamples-list","difficulty":"beginner","id":"examples-list","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-stepexamples-list"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-stepexamples-list"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-stepexamples-list"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-stepexamples-list"}]},{"codetabsId":"iris_intent_router_intents-stepexample-delete","difficulty":"beginner","id":"example-delete","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-stepexample-delete"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-stepexample-delete"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-stepexample-delete"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-stepexample-delete"}]},{"codetabsId":"iris_intent_router_intents-stepintent-delete","difficulty":"beginner","id":"intent-delete","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-stepintent-delete"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-stepintent-delete"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-stepintent-delete"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-stepintent-delete"}]},{"codetabsId":"iris_intent_router_intents-steprouter-clear","difficulty":"beginner","id":"router-clear","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_intent_router_intents-steprouter-clear"},{"clientId":"iris-typescript","clientName":"TypeScript (Iris)","id":"TypeScript (Iris)","langId":"typescript","panelId":"panel_TypeScript (Iris)_iris_intent_router_intents-steprouter-clear"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_intent_router_intents-steprouter-clear"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_intent_router_intents-steprouter-clear"}]}] } ``` ## Code examples These examples connect to Iris services using SDKs or HTTP requests with curl. Follow one language throughout each walkthrough. An intent is a named group of example phrases that represent one thing a user might ask for, such as tracking an order or requesting a refund. The intents you write and their examples decide how well a Router classifies messages. This page shows how to create, read, update, and delete intents and their examples, how to avoid overwriting someone else's changes, and how to write examples that match well. The examples use the connection values from the [quickstart](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/quickstart#save-connection-values) and an agent key with `write` access. Follow one tab throughout the page. ## Create or replace an intent Writing an intent with `PUT` creates it, or replaces the one with that name. It is idempotent: sending the same request twice produces the same intent, although each write returns a new `revision`. It returns `201` for a new intent and `200` for a replacement, and a replaced intent keeps its place in the list. In Python this is `define`, and in the CLI it is `intents add NAME`. Fields you leave out are cleared. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python intent = router.define( "refund", description="The customer wants their money back.", target=Target("agent", "billing-agent"), min_score=0.75, metadata={"owner": "support"}, examples=["i want a refund", "refund my purchase"], ) print(intent.name, intent.example_count, intent.revision) ``` ##### TypeScript (Iris) ```typescript const { result: intent } = await router.upsertIntent("refund", undefined, undefined, { description: "The customer wants their money back.", target: { type: "agent", ref: "billing-agent" }, minScore: 0.75, metadata: { owner: "support" }, examples: ["i want a refund", "refund my purchase"], }); console.log(intent.name, intent.exampleCount, intent.revision); ``` ##### cURL (Iris) ```bash ROUTER_API="${IRIS_INTENT_ROUTER_URL%/}/iris/data/v1/intent/routers/$IRIS_INTENT_ROUTER_ID" curl --fail-with-body --silent --show-error \ -X PUT "$ROUTER_API/intents/refund" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" \ -H 'Content-Type: application/json' \ --data '{ "description": "The customer wants their money back.", "target": {"type": "agent", "ref": "billing-agent"}, "minScore": 0.75, "metadata": {"owner": "support"}, "examples": ["i want a refund", "refund my purchase"] }' | jq -c '{name, exampleCount, revision}' ``` ##### CLI (Iris) ```bash iris intent-router intents add refund \ --description "The customer wants their money back." \ --target '{"type": "agent", "ref": "billing-agent"}' \ --min-score 0.75 --metadata owner=support \ --example "i want a refund" --example "refund my purchase" ``` An intent takes up to 256 examples, each up to 2,048 characters. Phrasings already on the intent that your request omits are removed after the new ones are written, so a concurrent match never sees an empty intent. ## Add several intents Add up to 100 intents in one request. They are added in the order you send them, after the intents the Router already has. An intent whose name already exists is replaced in place, and every other intent is left alone. Nothing is written if any intent is invalid. In Python this is `define_many`. The CLI's `intents add --file` reads a JSON or YAML file that holds a list of intents, or a mapping with an `intents` list. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python added = router.define_many( [ {"name": "track_order", "examples": ["where is my order", "track my package"]}, {"name": "cancel_order", "examples": ["cancel my order", "i changed my mind"]}, ] ) for item in added: print(item.name, item.example_count) ``` ##### TypeScript (Iris) ```typescript const { result } = await router.addIntents({ intents: [ { name: "track_order", examples: ["where is my order", "track my package"] }, { name: "cancel_order", examples: ["cancel my order", "i changed my mind"] }, ], }); for (const item of result.items) console.log(item.name, item.exampleCount); ``` ##### cURL (Iris) ```bash curl --fail-with-body --silent --show-error \ -X POST "$ROUTER_API/intents" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"intents": [ {"name": "track_order", "examples": ["where is my order", "track my package"]}, {"name": "cancel_order", "examples": ["cancel my order", "i changed my mind"]} ]}' | jq -c '.items[] | {name, exampleCount}' ``` ##### CLI (Iris) ```bash cat > intents.json <<'JSON' {"intents": [ {"name": "track_order", "examples": ["where is my order", "track my package"]}, {"name": "cancel_order", "examples": ["cancel my order", "i changed my mind"]} ]} JSON iris intent-router intents add --file intents.json ``` ## Read and list intents Reading an intent returns its configuration, `exampleCount`, timestamps, and `revision`. It doesn't include the examples, which you list separately. Listing returns intents with their configuration and example counts, in creation order. Pass `limit` (default 50, maximum 200). When more intents follow, the response includes `nextCursor`: pass it back as `cursor` for the next page. The Python `intents()` and `examples()` methods follow the cursor for you and return every item, and the CLI's `--all` does the same. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python for item in router.intents(): print(item.name, item.example_count) ``` ##### TypeScript (Iris) ```typescript const { result: page } = await router.listIntents(50); for (const item of page.items) console.log(item.name, item.exampleCount); console.log("next cursor:", page.nextCursor); ``` ##### cURL (Iris) ```bash curl --fail-with-body --silent --show-error \ "$ROUTER_API/intents?limit=50" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" > intents.json jq -c '.items[] | {name, exampleCount}' intents.json jq -r '"next cursor: \(.nextCursor)"' intents.json ``` ##### CLI (Iris) ```bash iris intent-router intents list --limit 50 ``` ## Update an intent's configuration Update the description, target, `minScore`, or metadata as a merge patch, without touching or re-embedding the examples. - An omitted field stays unchanged. - `null` clears `description`, `target`, `minScore`, or `metadata`. - A `metadata` map replaces the whole existing map. - An empty body is rejected. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python patched = router.update( "refund", min_score=None, target=Target("agent", "refunds-agent"), ) print(patched.name, patched.target, patched.min_score, patched.revision) ``` ##### TypeScript (Iris) ```typescript const { result: patched } = await router.updateIntent("refund", undefined, { minScore: null, target: { type: "agent", ref: "refunds-agent" }, }); console.log(patched.name, patched.target, patched.minScore, patched.revision); ``` ##### cURL (Iris) ```bash curl --fail-with-body --silent --show-error \ -X PATCH "$ROUTER_API/intents/refund" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"minScore": null, "target": {"type": "agent", "ref": "refunds-agent"}}' \ | jq -c '{name, target, minScore, revision}' ``` ##### CLI (Iris) ```bash iris intent-router intents update refund \ --target '{"type": "agent", "ref": "refunds-agent"}' ``` Clearing `minScore` makes the intent use the Router's threshold again. The CLI's `intents update` can't send `null`, so the CLI example changes only the target. To clear a field, use another client. ## Avoid overwriting concurrent changes Every intent has a `revision` that changes with each write to the intent. Read the intent, then send its revision as `expectedRevision` with your change, so the write succeeds only if nobody changed the intent in between. This example changes the description and leaves the rest of the intent alone. A conditional `PUT` works the same way but replaces the whole intent. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python current = router.intent("refund") changed = router.update( "refund", description="The customer wants a refund or a chargeback reversed.", expected_revision=current.revision, ) print(changed.name, changed.revision) ``` ##### TypeScript (Iris) ```typescript const { result: current } = await router.getIntent("refund"); const { result: changed } = await router.updateIntent("refund", undefined, { description: "The customer wants a refund or a chargeback reversed.", expectedRevision: current.revision, }); console.log(changed.name, changed.revision); ``` ##### cURL (Iris) ```bash REVISION=$(curl --fail-with-body --silent --show-error \ "$ROUTER_API/intents/refund" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" | jq -er .revision) curl --fail-with-body --silent --show-error \ -X PATCH "$ROUTER_API/intents/refund" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" \ -H 'Content-Type: application/json' \ --data "$(jq -n --arg rev "$REVISION" '{ description: "The customer wants a refund or a chargeback reversed.", expectedRevision: $rev }')" | jq -c '{name, revision}' ``` ##### CLI (Iris) ```bash REVISION=$(iris --json intent-router intents show refund | jq -er .revision) iris intent-router intents update refund \ --description "The customer wants a refund or a chargeback reversed." \ --expected-revision "$REVISION" ``` A stale revision fails with `412` and the type `/errors/revision-conflict`. Read the intent again, reapply your change, and retry. Because every write returns a new revision, a retry of a conditional write that already succeeded also fails with `412`: read the intent to check. Adding or deleting examples through the example operations doesn't change the revision. ## Manage examples Add phrasings to an existing intent. Each request takes 1 to 256 examples and adds them after the existing ones. Repeating a phrasing keeps its place and doesn't embed it again. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python for example in router.add_examples("refund", ["send my money back", "i was charged twice"]): print(example.example_id, example.text) ``` ##### TypeScript (Iris) ```typescript const { result: added } = await router.addExamples("refund", { examples: ["send my money back", "i was charged twice"], }); for (const example of added.items) console.log(example.exampleId, example.text); ``` ##### cURL (Iris) ```bash curl --fail-with-body --silent --show-error \ -X POST "$ROUTER_API/intents/refund/examples" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"examples": ["send my money back", "i was charged twice"]}' | jq -c '.items[] | {exampleId, text}' ``` ##### CLI (Iris) ```bash iris intent-router examples add refund "send my money back" "i was charged twice" ``` The response lists each example with its `exampleId`. List an intent's examples in the order they were written, with the same `limit` and `cursor` pagination as intents. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python examples = router.examples("refund") for example in examples: print(example.example_id, example.text) ``` ##### TypeScript (Iris) ```typescript const { result: examples } = await router.listExamples("refund", 50); for (const example of examples.items) console.log(example.exampleId, example.text); ``` ##### cURL (Iris) ```bash curl --fail-with-body --silent --show-error \ "$ROUTER_API/intents/refund/examples?limit=50" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" > examples.json jq -c '.items[] | {exampleId, text}' examples.json ``` ##### CLI (Iris) ```bash iris --json intent-router examples list refund --limit 50 > examples.json jq -c '.items[] | {exampleId, text}' examples.json ``` Read or delete one example by its identifier. Reading an identifier from another intent returns `404`. Deleting an example the intent doesn't hold succeeds and changes nothing, and deleting under an intent that doesn't exist returns `404`. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python router.remove_example("refund", examples[0].example_id) ``` ##### TypeScript (Iris) ```typescript await router.deleteExample("refund", examples.items[0].exampleId); ``` ##### cURL (Iris) ```bash EXAMPLE_ID=$(jq -er '.items[0].exampleId' examples.json) curl --fail-with-body --silent --show-error \ -X DELETE "$ROUTER_API/intents/refund/examples/$EXAMPLE_ID" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" ``` ##### CLI (Iris) ```bash EXAMPLE_ID=$(jq -er '.items[0].exampleId' examples.json) iris intent-router examples delete refund "$EXAMPLE_ID" --yes ``` ## Delete an intent Deleting an intent removes it and all its examples. Deleting a missing intent succeeds. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python router.remove("cancel_order") ``` ##### TypeScript (Iris) ```typescript await router.deleteIntent("cancel_order"); ``` ##### cURL (Iris) ```bash curl --fail-with-body --silent --show-error \ -X DELETE "$ROUTER_API/intents/cancel_order" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" ``` ##### CLI (Iris) ```bash iris intent-router intents delete cancel_order --yes ``` ## Clear a Router Clearing removes every intent and example and keeps the Router. The `scope` is required, and `INTENTS` is the only value. There is no default, so a request can't empty a Router by accident. Clearing also removes the quickstart's intents, which the [Match queries](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/match) examples create again before they run. **Available in:** Python (Iris), TypeScript (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python router.clear() ``` ##### TypeScript (Iris) ```typescript await router.clear({ scope: "INTENTS" }); ``` ##### cURL (Iris) ```bash curl --fail-with-body --silent --show-error \ -X POST "$ROUTER_API/clear" \ -H "Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"scope": "INTENTS"}' ``` ##### CLI (Iris) ```bash iris intent-router clear --scope intents --yes ``` ## Write good examples - **Vary the wording.** Include short and long phrasings, and the vocabulary your users really use. - **Keep each example about one thing.** An example that mixes two requests pulls the intent toward both. - **Separate overlapping intents.** If two intents keep matching the same queries, add examples that distinguish them, or raise their `minScore`. - **Add examples from real misses.** When a query returns the wrong intent or none, add it as an example of the right intent. See [Match queries](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/match) for how scores and thresholds interact with examples.