strukto-ai--mirage/docs/python/setup/dify.mdx

---
title: Dify
icon: /images/dify-logo.svg
description: Set up the Dify Knowledge resource in Python.
---

## Dependencies

No additional dependencies are required beyond the Python package. The Dify
resource uses `httpx` for async API calls.

For credential setup, see the [Dify Setup](/home/setup/dify) guide.

## Configuration

```python
import os

from mirage import MountMode, Workspace
from mirage.resource.dify import DifyConfig, DifyResource

config = DifyConfig(
    api_key=os.environ["DIFY_API_KEY"],
    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
    dataset_id=os.environ["DIFY_DATASET_ID"],
    slug_metadata_name=os.environ.get("DIFY_SLUG_METADATA_NAME", "slug"),
)
resource = DifyResource(config=config)
ws = Workspace({"/knowledge/": resource}, mode=MountMode.READ)
```

## Config Reference

| Field                | Required | Default | Description |
| -------------------- | -------- | ------- | ----------- |
| `api_key`            | Yes      |         | Dify Knowledge API key |
| `base_url`           | Yes      |         | Dify API base URL |
| `dataset_id`         | Yes      |         | Dify Knowledge dataset |
| `slug_metadata_name` | No       | `slug`  | Dify document metadata name used as the virtual path slug |

`DifyConfig` normalizes `base_url` by removing a trailing slash and trims
`slug_metadata_name`.

## Environment Example

```bash
# .env.development
DIFY_API_KEY=dataset-...
DIFY_BASE_URL=https://api.dify.ai/v1
DIFY_DATASET_ID=...
DIFY_SLUG_METADATA_NAME=slug
```

## Metadata Setup

For stable filesystem paths and scoped search, add a Dify document metadata
field named by `slug_metadata_name`. The default field name is `slug`.

```text
name: slug
value: guides/quickstart.md
```

If your Dify metadata field is named `path` instead, configure:

```python
config = DifyConfig(
    api_key=os.environ["DIFY_API_KEY"],
    base_url=os.environ.get("DIFY_BASE_URL", "https://api.dify.ai/v1"),
    dataset_id=os.environ["DIFY_DATASET_ID"],
    slug_metadata_name="path",
)
```

Mirage maps that document to:

```text
/knowledge/guides/quickstart.md
```

If a document does not have the configured slug metadata field, Mirage uses the
document name as the path. To make scoped `search` work for those name-based
documents, enable Dify's Built-in Fields in the dataset metadata settings so
`document_name` can be used as a metadata filter.

See [Dify Setup](/home/setup/dify#document-metadata) for the full metadata
checklist.