Dify knowledge bases, tags, and retrieval

Use this family to discover, create, configure, organize, query, or remove Dify knowledge bases. The thirteen operations use one workspace-scoped knowledge credential rather than an app credential.

Knowledge content, permissions, model choices, and retrieval records can contain confidential data. Bind each mutation to the exact workspace, knowledge base, approved change, and recovery evidence.

Choose an operation

These Tool operations have knowledge scope and no app-mode projection. The capability template is:

cap:dify:knowledge:<credential_id>:<operation>

The credential selects the workspace. A dataset, tag, attachment, or model ID cannot cross that credential boundary.

Discover knowledge bases

dataset.list accepts these Action query fields:

{
  "query": {
    "page": 1,
    "limit": 20,
    "keyword": "support",
    "tag_ids": ["tag-0190", "tag-0191"]
  }
}

The response contains data, has_more, limit, total, and page. Dataset details can include identity, provider, permission, indexing method, document statistics, embedding availability, retrieval settings, tags, and timestamps.

Use dataset.get with dataset_id for one complete record. The connector accepts a bounded path value, while the pinned provider requires a UUID and checks the caller’s dataset permission.

Create an empty knowledge base

dataset.create requires body.name from 1 to 40 characters. Description is optional and limited to 400 characters.

{
  "body": {
    "name": "Customer support knowledge",
    "description": "Approved support procedures and product facts.",
    "provider": "vendor",
    "permission": "partial_members",
    "indexing_technique": "high_quality",
    "embedding_model_provider": "provider-name",
    "embedding_model": "embedding-model-name"
  }
}

provider accepts internal vendor or configured external knowledge. Permission accepts only_me, all_team_members, or partial_members. The provider defaults are vendor, only_me, and an empty description.

Creation can also supply retrieval settings, external knowledge identifiers, and summary-index settings. Dify validates selected embedding and reranking models before creating the empty base.

A duplicate name is rejected. Successful creation returns status 200 with the dataset detail; no documents are created by this operation.

Update or delete a knowledge base

dataset.update requires dataset_id and sends only supplied body fields. Supported fields cover name, description, indexing, permission, embeddings, retrieval, partial members, and external knowledge settings.

{
  "dataset_id": "0190c42f-2d5a-7000-8000-000000000401",
  "body": {
    "description": "Reviewed support facts for the current release.",
    "permission": "all_team_members"
  }
}

Changing permission to only_me or all_team_members clears the partial member list. A partial_members change should include the intended member list. Model changes are validated against current workspace configuration.

dataset.delete permanently removes the base and its documents. Dify rejects deletion while an app uses the dataset and returns an empty 204 response after success. The connector represents the empty body as null.

Maintain workspace tags

Tag list returns all knowledge tags visible in the workspace. Each tag can include id, name, type, and a provider-coerced binding_count.

Create requires a 1-to-50 character name. Update requires tag_id and a new name. Delete requires tag_id, removes the tag, and does not delete tagged knowledge bases.

{
  "body": {
    "tag_id": "tag-0190",
    "name": "approved-support"
  }
}

Create and update require provider edit or dataset-editor permission. Delete requires edit permission. Create and update return the tag record; delete returns an empty 204 response.

Bind tags with non-empty tag_ids and target_id, where target_id is the knowledge-base ID. Unbind accepts the same normalized form:

{
  "body": {
    "tag_ids": ["tag-0190", "tag-0191"],
    "target_id": "0190c42f-2d5a-7000-8000-000000000401"
  }
}

The pinned provider also accepts legacy tag_id for unbinding. New Actions should use tag_ids. Bind and unbind require edit or dataset-editor permission and return empty 204 responses.

dataset.tag.get takes the provider UUID dataset ID and returns data plus total. Each bound entry contains tag ID and name.

Retrieve ranked chunks

dataset.retrieve requires dataset_id and a body query of at most 250 characters. It can also accept a retrieval model, external retrieval settings, and attachment IDs.

{
  "dataset_id": "0190c42f-2d5a-7000-8000-000000000401",
  "body": {
    "query": "How long is the approved refund window?",
    "retrieval_model": {
      "search_method": "semantic_search",
      "reranking_enable": false,
      "top_k": 5,
      "score_threshold_enabled": true,
      "score_threshold": 0.65
    }
  }
}

The provider checks dataset permission and initialization, then retrieves at most ten records internally. The response contains normalized query.content and records.

Each record contains a segment and score, with optional child chunks, files, position data, and summary. Segment details can expose document identity, content, answer, keywords, token counts, status, timestamps, and errors.

The connector classifies retrieval as a medium mutation. It therefore requires approval and an idempotency key and publishes no retry, even though the provider route performs a read-oriented search.

Apply mutation governance

All nine mutations require a non-blank Action idempotency key of at most 512 bytes. AIP retains its tenant-scoped reservation for 24 hours and revalidates the input hash on collision.

The reservation does not prove provider deduplication. These operations publish no automatic retry, transaction, reconciliation, cancellation, or compensation support.

Treat dataset configuration, permissions, tags, queries, chunks, attachments, model choices, and errors as confidential PII-bearing data. Redact sensitive values from general logs.

Recover safely

Preserve the Action ID, input digest, approval, idempotency key, credential, workspace, dataset, tag, model, and provider result evidence needed to settle an ambiguous outcome.

Related documentation

• Dify capability index
• Dify connector overview
• Dify connector configuration
• Authentication and credential scopes
• Errors and retry decisions