FastGPTFastGPT

Search Datasets API

Search across one or more readable datasets with semantic/hybrid recall, reranking, tag filters, and topk/maxTokens limits.

Endpoint Overview

  • Method : POST
  • Path : /api/core/dataset/search
  • Module : Datasets / Dataset Search
  • Authentication : Authorization: Bearer <apiKey>—Personal API Key (access scoped by team member permissions) (see API Getting Started )
  • Interactive Try-It-Out : Open in Scalar API Explorer (self-hosted instances: replace the origin with <instance>/apidoc/systemopenapi#tag/%E7%9F%A5%E8%AF%86%E5%BA%93%E6%90%9C%E7%B4%A2/POST/core/dataset/search )

Description & Notes

Search across one or more readable datasets using an API Key or login session. Vector recall requires matching active embedding models across target datasets, and results respect collection-level permissions. Choose either result.topk (returns top 1–100 items without token truncation) or result.maxTokens (truncates on complete chunks with no fixed cap); defaults to topk=20 when omitted, and prioritizes topk if both are sent. Response meta reports effective execution parameters.

Request Parameters

Request Body ( application/json )

FieldTypeRequiredDefaultConstraints & Description
scopeobjectYes-Search scope
scope.datasetIdsstring[]Yes-Target dataset IDs (max 100; deduplicated server-side with per-dataset read permission checks). minItems: 1; maxItems: 100
scope.filterobjectNo-Collection and tag filters (requires server-side filter support)
scope.filter.collectionIdsstring[]No-Restrict search to these collections or folders (intersected with other filters). minItems: 1; maxItems: 500
scope.filter.createTimeobjectNo-Collection creation time range
scope.filter.createTime.gtestringNo-Inclusive lower bound of creation time. pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
scope.filter.createTime.ltestringNo-Inclusive upper bound of creation time. pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
scope.filter.tagsobjectNo-Tag filter conditions; and and or groups are intersected
scope.filter.tags.andobject[]No-Tag conditions where all entries must match (AND). minItems: 1; maxItems: 50
scope.filter.tags.orobject[]No-Tag conditions where at least one entry must match (OR). minItems: 1; maxItems: 50
queryobjectYes-Search query input
query.textstringYes-Branch: text . Query text (max 10,000 chars after trimming); at least one of text or queryImageUrls is required. minLength: 1; maxLength: 10000
query.imageKeysstring[]No[]Branch: text . Temporary object keys for team-uploaded query images (max 10). maxItems: 10
query.imageKeysstring[]Yes-Branch: imageKeys . Temporary object keys for team-uploaded query images (max 10). minItems: 1; maxItems: 10
query.textstringNo""Branch: imageKeys . Query text (max 10,000 chars after trimming); at least one of text or queryImageUrls is required. maxLength: 10000
retrievalobjectNo{}Recall configuration
retrieval.modestring (enum)No"embedding"embedding , fullTextRecall , or mixedRecall . Allowed values: embedding , fullTextRecall , mixedRecall
retrieval.embeddingWeightnumberNo0.5Embedding fusion weight in mixed recall. min: 0; max: 1
rerankobjectNo{"enabled":false}Rerank configuration; do not pass model or weight when disabled
rerank.enabledfalseYes-Branch: enabled=false . Disable Rerank. Fixed: false
rerank.enabledtrueYes-Branch: enabled=true . Enable Rerank. Fixed: true
rerank.modelIdstringNo-Branch: enabled=true . Rerank model ID; uses the default accessible model if omitted. minLength: 1
rerank.candidateNumintegerNo-Branch: enabled=true . Rerank candidate pool size ( 10–100 ; defaults to 100 ). min: 10; max: 100
rerank.weightnumberNo0.5Branch: enabled=true . Fusion weight for rerank scores. min: 0; max: 1
queryExtensionobjectNo{"enabled":false}Query extension configuration
queryExtension.enabledfalseYes-Branch: enabled=false . Disable Query Extension. Fixed: false
queryExtension.enabledtrueYes-Branch: enabled=true . Enable Query Extension. Fixed: true
queryExtension.modelIdstringNo-Branch: enabled=true . Rerank model ID; uses the default accessible model if omitted. minLength: 1
queryExtension.backgroundstringNo""Branch: enabled=true . Background context helping the model interpret the query. maxLength: 100000
resultobjectNo{}Specify either topk or maxTokens ; defaults to topk=20 with no token budget
result.similaritynumberNo0Minimum similarity score threshold (applied when usingSimilarityFilter is enabled). min: 0; max: 1
result.maxTokensintegerYes-Branch: maxTokens . Total token budget across returned chunks (no fixed cap; preserves complete chunks, so the final chunk may exceed the budget). min: 1; max: 9007199254740991
result.topkintegerNo20Branch: anyOf #2 . Return top k ranked results ( 1–100 ; defaults to 20 when neither budget is set). min: 1; max: 100
usageScenestring (enum)No"search"Billing label: search for Dataset Search or searchTest for Search Test (does not affect retrieval or permissions). Allowed values: search , searchTest

Request Examples

Replace YOUR_API_KEY and placeholder IDs before running. Self-hosted users should replace the base URL with <instance>/api .

cURL Example

curl --fail-with-body -X POST "https://cloud.fastgpt.io/api/core/dataset/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "scope": {
    "datasetIds": [
      "507f1f77bcf86cd799439011"
    ]
  },
  "query": {
    "text": "How do I create a dataset?"
  }
}'

Minimal Valid JSON Body

{
  "scope": {
    "datasetIds": ["507f1f77bcf86cd799439011"]
  },
  "query": {
    "text": "How do I create a dataset?"
  }
}

Response Schema & Examples

Successful /api/* calls return the standard FastGPT envelope { "code": 200, "statusText": "", "message": "", "data": ... } , where data matches the 200 schema below (when a payload schema is declared; otherwise refer to the status description for runtime data semantics).

HTTP 200

Matched chunks and effective search metadata

Content-Type : application/json

FieldTypeRequiredDefaultConstraints & Description
listobject[]Yes-Merged and ranked dataset chunks
list[].qstringYes-Primary chunk content / question
list[].astringNo-Supplementary answer / text
list[].imageIdstringNo-Image ID
list[].idstringYes-Data item ID. pattern: ^[0-9a-fA-F]{24}$
list[].datasetIdstringYes-Dataset ID. pattern: ^[0-9a-fA-F]{24}$
list[].collectionIdstringYes-Collection ID. pattern: ^[0-9a-fA-F]{24}$
list[].imagePreivewUrlstringNo-Image preview URL
list[].updateTimestringYes-Update time
list[].sourceNamestringYes-Source name
list[].sourceIdstringNo-Source ID
list[].chunkIndexnumberYes-Chunk index
list[].indexStatusstring (enum)No-Index status (absent on legacy already-indexed records). Allowed values: indexing , indexed , error , rebuildIndexPending , rebuildIndexRunning , rebuildIndexFailed , rebuildSynonymPending , rebuildSynonymRunning , rebuildSynonymFailed
list[].indexErrorMsgstringNo-Indexing error details
list[].imageDescMapobjectNo-Image description mapping
list[].scoreobject[]Yes-Retrieval score breakdown list
list[].score[].typestring (enum)Yes-Score type. Allowed values: embedding , fullText , reRank , rrf
list[].score[].valuenumberYes-Score value
list[].score[].indexnumberYes-Index
list[].metadataobjectNo-Custom metadata
list[].retrievalRanknumberNo-Retrieval rank
list[].synonymMappingsobjectNo-Mapping from original terms appearing in chunks or user questions to canonical terms
metaobjectYes--
meta.durationMsnumberYes-Search latency in milliseconds. min: 0
meta.usingSimilarityFilterbooleanYes-Whether similarity filtering was applied
meta.usingReRankbooleanYes-Whether reranking was executed
meta.queryExtensionModelIdstringNo-Model ID used for query extension
Edit on GitHub

Last updated

On this page

Put your business knowledge to work with AI

Import company documents and build accurate, reliable, traceable AI answers.