Dify Octri Demo
POST/datasets/{dataset_id}/retrieve

Retrieve relevant chunks from a knowledge base

Retrieves the chunks most relevant to a query from a knowledge base for production or test retrieval. Supply query and retrieval_model to configure the search method, result limit, and optional reranking or score filtering.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 4 body fields
dataset_idstringrequired
The UUID of the knowledge base to search.

Retrieval query and settings. query and the search_method, reranking_enable, top_k, and score_threshold_enabled fields within retrieval_model are required.

attachment_idsarray<string>optional
List of attachment IDs to include in the retrieval context.
external_retrieval_modelobjectoptional
Retrieval settings for external knowledge bases.
querystringrequired
Search query text.
retrieval_modelobjectoptional
Retrieval settings. Includes the search method (`keyword_search`, `semantic_search`, `full_text_search`, or `hybrid_search`), reranking settings, maximum results (`top_k`), and score threshold settings. `reranking_mode` accepts `reranking_model` or `weighted_score` and is required when reranking is enabled. May also include metadata filtering conditions, reranking model configuration, and weight configuration for hybrid search.

5 status codes
200Returns the original query and an array of matched retrieval records, including segment, score, summary, file, child-chunk, and position data where available.
queryobjectoptional
The original query object.
recordsarray<object>optional
List of matched retrieval records.
400Returned when a request parameter is invalid, the knowledge base is still initializing or indexing, provider credentials are missing or the provider quota is exhausted, the selected model is unsupported, or the model request fails.

6 documented failures

  • completion_request_error

    Completion request failed.

    completion_request_error

  • dataset_not_initialized

    The dataset is still being initialized or indexing. Please wait a moment.

    dataset_not_initialized

  • invalid_param

    Invalid parameter value.

    invalid_param

  • model_currently_not_support

    Dify Hosted OpenAI trial currently not support the GPT-4 model.

    model_currently_not_support

  • provider_not_initialize

    No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.

    provider_not_initialize

  • provider_quota_exceeded

    Your quota for Dify Hosted Model Provider has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.

    provider_quota_exceeded

403Returned when API access is disabled for the knowledge base, its request rate limit has been reached, or the API key is not scoped to that knowledge base.

One documented failure

  • forbidden

    Dataset api access is not enabled.

    forbidden (api access)

404Returned when no knowledge base matches the supplied `dataset_id`.

One documented failure

  • not_found

    Dataset not found.

    not_found

500Returned when an internal error occurs during retrieval.

One documented failure

  • internal_server_error

    An internal error occurred.

    internal_server_error

Error handling

A 400 is returned when a request parameter is invalid or retrieval fails because the knowledge base, provider, quota, or selected model is unavailable. A 403 is returned when API access is disabled, the request rate limit is reached, or the API key is not scoped to the knowledge base; a 404 is returned when no knowledge base matches the dataset_id path parameter, and a 500 indicates an internal retrieval error. The dataset_id path parameter must be a UUID; query is required and limited to 250 characters, and retrieval_model must include search_method, reranking_enable, top_k, and score_threshold_enabled; search_method must be keyword_search, semantic_search, full_text_search, or hybrid_search, and reranking_mode is required when reranking_enable is true.