---
title: "Creating URL Redirect Rules for Ambient Knowledge"
description: "Introduction"
canonical_url: "https://help.brainfi.sh/articles/creating-url-redirect-rules-for-ambient-knowledge-UnqVaSuZS2"
md_url: "https://help.brainfi.sh/articles/creating-url-redirect-rules-for-ambient-knowledge-UnqVaSuZS2.md"
---
# Creating URL Redirect Rules for Ambient Knowledge

## Introduction

The `redirectRules` feature provides a powerful way to transform URLs in your ambient knowledge content. This is particularly useful when you need to rewrite links to be generalistic or when migrating between different URL structures while maintaining backward compatibility.


## What are Redirect Rules?

Redirect rules allow you to define patterns for URLs and specify how they should be transformed when displayed to users. Each rule consists of:


1. A **source pattern** - The URL pattern to match against
2. A **destination pattern** - The pattern to transform the matched URL into

The rules use [path-to-regexp](https://github.com/pillarjs/path-to-regexp) syntax, which is the same pattern matching system used by popular routing libraries like React Router.


## How to Define Redirect Rules

Redirect rules are defined as an array of objects with `source` and `destination` properties:

```markup
<script type="module">
  import Brainfish from "https://cdn.jsdelivr.net/npm/@brainfish-ai/web-widget@latest/dist/web.js";
  
  // Initialize Brainfish widget
  Brainfish.Widgets.init({
    widgetKey: "your_brainfish_widget_key",
    overrides: {
      redirectRules: [
        {
          source: '/knowledge/:id/:path',
          destination: '/knowledge/example/:path'
        },
        {
          source: '/docs/:version/api/:endpoint',
          destination: '/api/:endpoint'
        }
      ]
    }
  });
</script>
```

### Pattern Syntax

* **Parameters**: Use `:paramName` to define a named parameter in your pattern (e.g., `:id` matches a segment up to the next slash)
* **Optional parameters**: Use braces to define optional parts: `/users{/:id}/profile` (the `/:id` part is optional)
* **Wildcard**: Use `*paramName` to match multiple segments across slashes (e.g., `/*splat` in `/api/*splat` would match `/api/users/123` with `splat` being `['users', '123']`)

For more advanced pattern matching options and detailed syntax, refer to the [path-to-regexp documentation](https://github.com/pillarjs/path-to-regexp).

## Why Redirect Rules are Useful

Redirect rules help improve the quality of both manual and ambient knowledge articles by ensuring article links are relevant.

### Improved Search Experience

When users search for content, they expect to find the most relevant information regardless of URL structure changes. Redirect rules ensure that:

* **Search results remain relevant**: Even if content has moved to a new location, search results can display the current, correct URLs.
* **Links within search results work properly**: When search results include links to other content, these links are automatically transformed to point to the correct locations.
* **Consistent user experience**: Users don't encounter broken links or need to manually navigate to new locations.

### Content Evolution Support

As your knowledge base grows and evolves:

* **URL structures can change**: Teams often reorganize content hierarchies as they scale.
* **Content migrations become seamless**: When moving from one platform to another, redirect rules maintain link integrity.
* **Historical references remain valid**: References to older content paths continue to work without manual updates.

### What It Looks Like in Practice

In search results and rendered content, redirect rules work invisibly to users:

```
Original link in content: /old-docs/getting-started/installation

What the user sees: /documentation/getting-started/installation
```

The transformation happens automatically when content is rendered, with no visible difference to the end user except that the links now point to valid locations.

When hovering over links in search results or clicking through to content, users will always be directed to the current, valid URL rather than encountering 404 errors or being required to manually find the new location.

## Best Practices


1. **Order matters**: Rules are evaluated in order, so place more specific rules before more general ones
2. **Test thoroughly**: Test your rules with various URL patterns to ensure they work as expected
3. **Keep it simple**: Use the minimum number of rules needed to achieve your goal
4. **Document your rules**: Keep documentation of your URL transformation rules for future reference


## Conclusion

The `redirectRules` feature provides a flexible way to handle URL transformations in your agent search results. By defining simple pattern-matching rules, you can ensure that links in your content are always up-to-date and point to the correct locations, even as your URL structure evolves.

This feature is particularly valuable for applications with large amounts of content or those undergoing structural changes, as it allows you to maintain link integrity without having to update every piece of content manually.