Skip to main content
API docs by Redocly

NucliaDB Agentic API (v1)

API reference for NucliaDB Agentic API endpoints. Requires a Knowledge Box API Key.

Agentic configs

Agentic configuration endpoints.

List agentic configurations

path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Create agentic configuration

path Parameters
kbid
required
string (Kbid)
agentic_id
required
string (Agentic Id)
Request Body schema: application/json
required
Title (string) or Title (null) (Title)
AgenticRephraseConfiguration (object) or null
AgenticSmartAgentConfiguration (object) or null
AgenticSummarizeConfiguration (object) or null

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "rephrase": {
    },
  • "smart_agent": {
    },
  • "summarize": {
    }
}

Response samples

Content type
application/json
null

Get agentic configuration

path Parameters
kbid
required
string (Kbid)
agentic_id
required
string (Agentic Id)

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "rephrase": {
    },
  • "smart_agent": {
    },
  • "summarize": {
    }
}

Update agentic configuration

path Parameters
kbid
required
string (Kbid)
agentic_id
required
string (Agentic Id)
Request Body schema: application/json
required
Title (string) or Title (null) (Title)
AgenticRephraseConfiguration (object) or null
AgenticSmartAgentConfiguration (object) or null
AgenticSummarizeConfiguration (object) or null

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "rephrase": {
    },
  • "smart_agent": {
    },
  • "summarize": {
    }
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Ask

Agentic Ask endpoints.

Ask Knowledge Box

Ask questions on a Knowledge Box

path Parameters
kbid
required
string (Kbid)
header Parameters
x-ndb-client
string (NucliaDBClientType)
Default: api
Enum: "api" "widget" "web" "dashboard" "desktop" "chrome_extension"
x-show-consumption
boolean (X-Show-Consumption)
Default: false
x-nucliadb-user
string (X-Nucliadb-User)
Default:
x-forwarded-for
string (X-Forwarded-For)
Default:
x-synchronous
boolean (X-Synchronous)
Default: false

When set to true, outputs response as JSON in a non-streaming way. This is slower and requires waiting for entire answer to be ready.

Request Body schema: application/json
required
Audit metadata (object) or Audit metadata (null) (Audit metadata)

A dictionary containing optional audit-specific metadata, such as user_id, environment, or other contextual information. This metadata can be leveraged for filtering and analyzing activity logs in future operations. Each key-value pair represents a piece of metadata relevant to the user's request.

query
required
string (Query) <= 20000 characters

The query to get a generative answer for

Agentic configuration ID (string) or Agentic configuration ID (null) (Agentic configuration ID)

The ID of the agentic configuration to use for this request. If not provided, the default retrieval and generation parameters of the Knowledge Box will be used. If provided, the parameters in the agentic configuration will override the parameters in the request. Note that the query field in the agentic configuration will be ignored, and the query in the request will be used instead.

top_k
integer (Top k) [ 1 .. 200 ]
Default: 20

The top most relevant results to fetch at the retrieval step. The maximum number of results allowed is 200.

FilterExpression (object) or Filter resource by an expression (null) (Filter resource by an expression)

Returns only documents that match this filter expression.Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters This allows building complex filtering expressions and replaces the following parameters:fields, filters, range_*, resource_filters, keyword_filters.

fields
Array of strings (Fields)
Default: []

The list of fields to search in. For instance: a/title to search only on title field. For more details on filtering by field, see: https://docs.nuclia.dev/docs/rag/advanced/search/#search-in-a-specific-field.

Array of Search Filters (strings) or Array of Search Filters (objects) (Search Filters)
Default: []

The list of filters to apply. Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters

Array of Keyword filters (strings) or Array of Keyword filters (objects) (Keyword filters)
Default: []

List of keyword filter expressions to apply to the retrieval step. The text block search will only be performed on the documents that contain the specified keywords. The filters are case-insensitive, and only alphanumeric characters and spaces are allowed. Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters

Vectorset (string) or Vectorset (null) (Vectorset)

Vectors index to perform the search in. If not provided, NucliaDB will use the default one

Minimum score (number) or MinScore (object) or Minimum score (null) (Minimum score)

Minimum score to filter search results. Results with a lower score will be ignored. Accepts either a float or a dictionary with the minimum scores for the bm25 and vector indexes. If a float is provided, it is interpreted as the minimum score for vector index search.

features
Array of strings (Chat features)
Default: ["semantic","keyword"]
Items Enum: "keyword" "relations" "semantic"

Features enabled for the chat endpoint. Semantic search is done if semantic is included. If keyword is included, the results will include matching paragraphs from the bm25 index. If relations is included, a graph of entities related to the answer is returned. paragraphs and vectors are deprecated, please use keyword and semantic instead

Resource creation range start (string) or Resource creation range start (null) (Resource creation range start)

Resources created before this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

Resource creation range end (string) or Resource creation range end (null) (Resource creation range end)

Resources created after this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

Resource modification range start (string) or Resource modification range start (null) (Resource modification range start)

Resources modified before this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

Resource modification range end (string) or Resource modification range end (null) (Resource modification range end)

Resources modified after this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

show
Array of strings (Show metadata)
Default: ["basic"]
Items Enum: "basic" "origin" "extra" "relations" "values" "extracted" "errors" "security"

Controls which types of metadata are serialized on resources of search results

field_type_filter
Array of strings (Field type filter)
Default: ["text","file","link","conversation","generic","key_value"]
Items Enum: "text" "file" "link" "conversation" "generic" "key_value"

Define which field types are serialized on resources of search results

extracted
Array of strings (Extracted metadata)
Deprecated
Default: []
Items Enum: "text" "metadata" "shortened_metadata" "large_metadata" "vectors" "link" "file" "question_answers" "relation_vectors"

[Deprecated] Please use GET resource endpoint instead to get extracted metadata

Array of Chat context (deprecated) (objects) or Chat context (deprecated) (null) (Chat context (deprecated))
Deprecated

DEPRECATED! Please, use chat_history instead.

Array of Chat history (objects) or Chat history (null) (Chat history)

Use to rephrase the new LLM query by taking into account the chat conversation history. This will be passed to the LLM so that it is aware of the previous conversation.

Array of Extra query context (strings) or Extra query context (null) (Extra query context)

Additional context that is added to the retrieval context sent to the LLM. It allows extending the chat feature with content that may not be in the Knowledge Box.

Array of Extra query context images (objects) or Extra query context images (null) (Extra query context images)

Additional images added to the retrieval context sent to the LLM." It allows extending the chat feature with content that may not be in the Knowledge Box.

Image (object) or Query image (null) (Query image)

Image that will be used together with the query text for retrieval and then sent to the LLM as part of the context. If a query image is provided, the extra_context_images and rag_images_strategies will be disabled.

highlight
boolean (Highlight)
Default: false

If set to true, the query terms will be highlighted in the results between ... tags

resource_filters
Array of strings (Resources filter)
Default: []

List of resource ids to filter search results for. Only paragraphs from the specified resources will be returned.

Prompts (string) or CustomPrompt (object) or Prompts (null) (Prompts)

Use to customize the prompts given to the generative model. Both system and user prompts can be customized. If a string is provided, it is interpreted as the user prompt.

RankFusionName (string) or Rank fusion (any) (Rank fusion)
Default: "rrf"

Rank fusion algorithm to use to merge results from multiple retrievers (keyword, semantic)

RerankerName (string) or Reranker (any) (Reranker)
Default: "predict"

Reranker let you specify which method you want to use to rerank your results at the end of retrieval

Citations (boolean) or CitationsType (string) or Citations (null) (Citations)

Whether to include citations in the response. If set to None or False, no citations will be computed. If set to True or 'default', citations will be computed after answer generation and send as a separate CitationsGenerativeResponse chunk. If set to 'llm_footnotes', citations will be included in the LLM's response as markdown-styled footnotes. A FootnoteCitationsGenerativeResponse chunk will also be sent to map footnote ids to context keys in the query_context.

Citation Threshold (number) or Citation Threshold (null) (Citation Threshold)

If citations is set to True or 'default', this will be the similarity threshold. Value between 0 and 1, lower values will produce more citations. If not set, it will be set to the optimized threshold found by Nuclia.

RequestSecurity (object) or Security (null) (Security)

Security metadata for the request. Please refer to the documentation for more details on how security works: https://docs.rag.progress.cloud/docs/management/how-to/restrict-access

show_hidden
boolean (Show hidden resources)
Default: false

If set to false (default), excludes hidden resources from search

Array of any (RAG context building strategies)
Default: []

Options for tweaking how the context for the LLM model is crafted:

  • full_resource will add the full text of the matching resources to the context. This strategy cannot be combined with hierarchy, neighbouring_paragraphs, or field_extension.
  • field_extension will add the text of the matching resource's specified fields to the context.
  • hierarchy will add the title and summary text of the parent resource to the context for each matching paragraph.
  • neighbouring_paragraphs will add the sorrounding paragraphs to the context for each matching paragraph.
  • metadata_extension will add the metadata of the matching paragraphs or its resources to the context.
  • prequeries allows to run multiple retrieval queries before the main query and add the results to the context. The results of specific queries can be boosted by the specifying weights.

If empty, the default strategy is used, which simply adds the text of the matching paragraphs to the context.

Array of any (RAG image context building strategies)
Default: []

Options for tweaking how the image based context for the LLM model is crafted:

  • page_image will add the full page image of the matching resources to the context.
  • tables will send the table images for the paragraphs that contain tables and matched the retrieval query.
  • paragraph_image will add the images of the paragraphs that contain images (images for tables are not included). No image strategy is used by default. Note that this is only available for LLM models that support visual inputs. If the model does not support visual inputs, the image strategies will be ignored.
debug
boolean (Debug mode)
Default: false

If set, the response will include some extra metadata for debugging purposes, like the list of queried nodes.

Generative model (string) or Generative model (null) (Generative model)

The generative model to use for the chat endpoint. If not provided, the model configured for the Knowledge Box is used.

Seed for the generative model (integer) or Seed for the generative model (null) (Seed for the generative model)

The seed to use for the generative model for deterministic generation. Only supported by some models.

Maximum LLM tokens to use for the request (integer) or MaxTokens (object) or Maximum LLM tokens to use for the request (null) (Maximum LLM tokens to use for the request)

Use to limit the amount of tokens used in the LLM context and/or for generating the answer. If not provided, the default maximum tokens of the generative model will be used. If an integer is provided, it is interpreted as the maximum tokens for the answer.

rephrase
boolean (Rephrase)
Default: false

Rephrase the query for a more efficient retrieval. This will consume LLM tokens and make the request slower.

Chat History Relevance Threshold (number) or Chat History Relevance Threshold (null) (Chat History Relevance Threshold)

Threshold to determine if the past chat history is relevant to rephrase the user's question. 0 - Always treat previous messages as relevant (always rephrase).1 - Always treat previous messages as irrelevant (never rephrase).Values in between adjust the sensitivity.

prefer_markdown
boolean (Prefer markdown)
Default: false

If set to true, the response will be in markdown format

Answer JSON schema (object) or Answer JSON schema (null) (Answer JSON schema)

Desired JSON schema for the LLM answer. This schema is passed to the LLM so that it answers in a scructured format following the schema. If not provided, textual response is returned. Note that when using this parameter, the answer in the generative response will not be returned in chunks, the whole response text will be returned instead. Using this feature also disables the citations parameter. For maximal accuracy, please include a description for each field of the schema.

generate_answer
boolean (Generate Answer)
Default: true

Whether to generate an answer using the generative model. If set to false, the response will only contain the retrieval results.

Search Configuration (string) or Search Configuration (null) (Search Configuration)

Load ask parameters from this configuration. Parameters in the request override parameters from the configuration.

Reasoning (object) or Reasoning options (boolean) (Reasoning options)
Default: false

Reasoning options for the generative model. Set to True to enable default reasoning, False to disable, or provide a Reasoning object for custom options.

Responses

Request samples

Content type
application/json
{
  • "audit_metadata": {
    },
  • "query": "string",
  • "agentic_config_id": "string",
  • "top_k": 20,
  • "filter_expression": {
    },
  • "fields": [ ],
  • "filters": [ ],
  • "keyword_filters": [
    ],
  • "vectorset": "string",
  • "min_score": 0,
  • "features": [
    ],
  • "range_creation_start": "2019-08-24T14:15:22Z",
  • "range_creation_end": "2019-08-24T14:15:22Z",
  • "range_modification_start": "2019-08-24T14:15:22Z",
  • "range_modification_end": "2019-08-24T14:15:22Z",
  • "show": [
    ],
  • "field_type_filter": [
    ],
  • "extracted": [ ],
  • "context": [
    ],
  • "chat_history": [
    ],
  • "extra_context": [
    ],
  • "extra_context_images": [
    ],
  • "query_image": {
    },
  • "highlight": false,
  • "resource_filters": [ ],
  • "prompt": "string",
  • "rank_fusion": "rrf",
  • "reranker": "predict",
  • "citations": true,
  • "citation_threshold": 1,
  • "security": {
    },
  • "show_hidden": false,
  • "rag_strategies": [
    ],
  • "rag_images_strategies": [ ],
  • "debug": false,
  • "generative_model": "string",
  • "generative_model_seed": 0,
  • "max_tokens": 0,
  • "rephrase": false,
  • "chat_history_relevance_threshold": 1,
  • "prefer_markdown": false,
  • "answer_json_schema": {
    },
  • "generate_answer": true,
  • "search_configuration": "string",
  • "reasoning": false
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "reasoning": "string",
  • "answer_json": { },
  • "status": "string",
  • "retrieval_results": {
    },
  • "retrieval_best_matches": [ ],
  • "prequeries": {
    },
  • "learning_id": "",
  • "relations": {
    },
  • "citations": { },
  • "citation_footnote_to_context": {
    },
  • "augmented_context": {
    },
  • "prompt_context": [
    ],
  • "predict_request": { },
  • "metadata": {
    },
  • "consumption": {
    },
  • "error_details": "string",
  • "debug": { }
}

Ask a resource (by id)

Ask questions to a resource

path Parameters
kbid
required
string (Kbid)
rid
required
string <uuid> (Rid)
header Parameters
x-show-consumption
boolean (X-Show-Consumption)
Default: false
x-ndb-client
string (NucliaDBClientType)
Default: api
Enum: "api" "widget" "web" "dashboard" "desktop" "chrome_extension"
x-nucliadb-user
string (X-Nucliadb-User)
Default:
x-forwarded-for
string (X-Forwarded-For)
Default:
x-synchronous
boolean (X-Synchronous)
Default: false

When set to true, outputs response as JSON in a non-streaming way. This is slower and requires waiting for entire answer to be ready.

Request Body schema: application/json
required
Audit metadata (object) or Audit metadata (null) (Audit metadata)

A dictionary containing optional audit-specific metadata, such as user_id, environment, or other contextual information. This metadata can be leveraged for filtering and analyzing activity logs in future operations. Each key-value pair represents a piece of metadata relevant to the user's request.

query
required
string (Query) <= 20000 characters

The query to get a generative answer for

Agentic configuration ID (string) or Agentic configuration ID (null) (Agentic configuration ID)

The ID of the agentic configuration to use for this request. If not provided, the default retrieval and generation parameters of the Knowledge Box will be used. If provided, the parameters in the agentic configuration will override the parameters in the request. Note that the query field in the agentic configuration will be ignored, and the query in the request will be used instead.

top_k
integer (Top k) [ 1 .. 200 ]
Default: 20

The top most relevant results to fetch at the retrieval step. The maximum number of results allowed is 200.

FilterExpression (object) or Filter resource by an expression (null) (Filter resource by an expression)

Returns only documents that match this filter expression.Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters This allows building complex filtering expressions and replaces the following parameters:fields, filters, range_*, resource_filters, keyword_filters.

fields
Array of strings (Fields)
Default: []

The list of fields to search in. For instance: a/title to search only on title field. For more details on filtering by field, see: https://docs.nuclia.dev/docs/rag/advanced/search/#search-in-a-specific-field.

Array of Search Filters (strings) or Array of Search Filters (objects) (Search Filters)
Default: []

The list of filters to apply. Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters

Array of Keyword filters (strings) or Array of Keyword filters (objects) (Keyword filters)
Default: []

List of keyword filter expressions to apply to the retrieval step. The text block search will only be performed on the documents that contain the specified keywords. The filters are case-insensitive, and only alphanumeric characters and spaces are allowed. Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters

Vectorset (string) or Vectorset (null) (Vectorset)

Vectors index to perform the search in. If not provided, NucliaDB will use the default one

Minimum score (number) or MinScore (object) or Minimum score (null) (Minimum score)

Minimum score to filter search results. Results with a lower score will be ignored. Accepts either a float or a dictionary with the minimum scores for the bm25 and vector indexes. If a float is provided, it is interpreted as the minimum score for vector index search.

features
Array of strings (Chat features)
Default: ["semantic","keyword"]
Items Enum: "keyword" "relations" "semantic"

Features enabled for the chat endpoint. Semantic search is done if semantic is included. If keyword is included, the results will include matching paragraphs from the bm25 index. If relations is included, a graph of entities related to the answer is returned. paragraphs and vectors are deprecated, please use keyword and semantic instead

Resource creation range start (string) or Resource creation range start (null) (Resource creation range start)

Resources created before this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

Resource creation range end (string) or Resource creation range end (null) (Resource creation range end)

Resources created after this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

Resource modification range start (string) or Resource modification range start (null) (Resource modification range start)

Resources modified before this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

Resource modification range end (string) or Resource modification range end (null) (Resource modification range end)

Resources modified after this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

show
Array of strings (Show metadata)
Default: ["basic"]
Items Enum: "basic" "origin" "extra" "relations" "values" "extracted" "errors" "security"

Controls which types of metadata are serialized on resources of search results

field_type_filter
Array of strings (Field type filter)
Default: ["text","file","link","conversation","generic","key_value"]
Items Enum: "text" "file" "link" "conversation" "generic" "key_value"

Define which field types are serialized on resources of search results

extracted
Array of strings (Extracted metadata)
Deprecated
Default: []
Items Enum: "text" "metadata" "shortened_metadata" "large_metadata" "vectors" "link" "file" "question_answers" "relation_vectors"

[Deprecated] Please use GET resource endpoint instead to get extracted metadata

Array of Chat context (deprecated) (objects) or Chat context (deprecated) (null) (Chat context (deprecated))
Deprecated

DEPRECATED! Please, use chat_history instead.

Array of Chat history (objects) or Chat history (null) (Chat history)

Use to rephrase the new LLM query by taking into account the chat conversation history. This will be passed to the LLM so that it is aware of the previous conversation.

Array of Extra query context (strings) or Extra query context (null) (Extra query context)

Additional context that is added to the retrieval context sent to the LLM. It allows extending the chat feature with content that may not be in the Knowledge Box.

Array of Extra query context images (objects) or Extra query context images (null) (Extra query context images)

Additional images added to the retrieval context sent to the LLM." It allows extending the chat feature with content that may not be in the Knowledge Box.

Image (object) or Query image (null) (Query image)

Image that will be used together with the query text for retrieval and then sent to the LLM as part of the context. If a query image is provided, the extra_context_images and rag_images_strategies will be disabled.

highlight
boolean (Highlight)
Default: false

If set to true, the query terms will be highlighted in the results between ... tags

resource_filters
Array of strings (Resources filter)
Default: []

List of resource ids to filter search results for. Only paragraphs from the specified resources will be returned.

Prompts (string) or CustomPrompt (object) or Prompts (null) (Prompts)

Use to customize the prompts given to the generative model. Both system and user prompts can be customized. If a string is provided, it is interpreted as the user prompt.

RankFusionName (string) or Rank fusion (any) (Rank fusion)
Default: "rrf"

Rank fusion algorithm to use to merge results from multiple retrievers (keyword, semantic)

RerankerName (string) or Reranker (any) (Reranker)
Default: "predict"

Reranker let you specify which method you want to use to rerank your results at the end of retrieval

Citations (boolean) or CitationsType (string) or Citations (null) (Citations)

Whether to include citations in the response. If set to None or False, no citations will be computed. If set to True or 'default', citations will be computed after answer generation and send as a separate CitationsGenerativeResponse chunk. If set to 'llm_footnotes', citations will be included in the LLM's response as markdown-styled footnotes. A FootnoteCitationsGenerativeResponse chunk will also be sent to map footnote ids to context keys in the query_context.

Citation Threshold (number) or Citation Threshold (null) (Citation Threshold)

If citations is set to True or 'default', this will be the similarity threshold. Value between 0 and 1, lower values will produce more citations. If not set, it will be set to the optimized threshold found by Nuclia.

RequestSecurity (object) or Security (null) (Security)

Security metadata for the request. Please refer to the documentation for more details on how security works: https://docs.rag.progress.cloud/docs/management/how-to/restrict-access

show_hidden
boolean (Show hidden resources)
Default: false

If set to false (default), excludes hidden resources from search

Array of any (RAG context building strategies)
Default: []

Options for tweaking how the context for the LLM model is crafted:

  • full_resource will add the full text of the matching resources to the context. This strategy cannot be combined with hierarchy, neighbouring_paragraphs, or field_extension.
  • field_extension will add the text of the matching resource's specified fields to the context.
  • hierarchy will add the title and summary text of the parent resource to the context for each matching paragraph.
  • neighbouring_paragraphs will add the sorrounding paragraphs to the context for each matching paragraph.
  • metadata_extension will add the metadata of the matching paragraphs or its resources to the context.
  • prequeries allows to run multiple retrieval queries before the main query and add the results to the context. The results of specific queries can be boosted by the specifying weights.

If empty, the default strategy is used, which simply adds the text of the matching paragraphs to the context.

Array of any (RAG image context building strategies)
Default: []

Options for tweaking how the image based context for the LLM model is crafted:

  • page_image will add the full page image of the matching resources to the context.
  • tables will send the table images for the paragraphs that contain tables and matched the retrieval query.
  • paragraph_image will add the images of the paragraphs that contain images (images for tables are not included). No image strategy is used by default. Note that this is only available for LLM models that support visual inputs. If the model does not support visual inputs, the image strategies will be ignored.
debug
boolean (Debug mode)
Default: false

If set, the response will include some extra metadata for debugging purposes, like the list of queried nodes.

Generative model (string) or Generative model (null) (Generative model)

The generative model to use for the chat endpoint. If not provided, the model configured for the Knowledge Box is used.

Seed for the generative model (integer) or Seed for the generative model (null) (Seed for the generative model)

The seed to use for the generative model for deterministic generation. Only supported by some models.

Maximum LLM tokens to use for the request (integer) or MaxTokens (object) or Maximum LLM tokens to use for the request (null) (Maximum LLM tokens to use for the request)

Use to limit the amount of tokens used in the LLM context and/or for generating the answer. If not provided, the default maximum tokens of the generative model will be used. If an integer is provided, it is interpreted as the maximum tokens for the answer.

rephrase
boolean (Rephrase)
Default: false

Rephrase the query for a more efficient retrieval. This will consume LLM tokens and make the request slower.

Chat History Relevance Threshold (number) or Chat History Relevance Threshold (null) (Chat History Relevance Threshold)

Threshold to determine if the past chat history is relevant to rephrase the user's question. 0 - Always treat previous messages as relevant (always rephrase).1 - Always treat previous messages as irrelevant (never rephrase).Values in between adjust the sensitivity.

prefer_markdown
boolean (Prefer markdown)
Default: false

If set to true, the response will be in markdown format

Answer JSON schema (object) or Answer JSON schema (null) (Answer JSON schema)

Desired JSON schema for the LLM answer. This schema is passed to the LLM so that it answers in a scructured format following the schema. If not provided, textual response is returned. Note that when using this parameter, the answer in the generative response will not be returned in chunks, the whole response text will be returned instead. Using this feature also disables the citations parameter. For maximal accuracy, please include a description for each field of the schema.

generate_answer
boolean (Generate Answer)
Default: true

Whether to generate an answer using the generative model. If set to false, the response will only contain the retrieval results.

Search Configuration (string) or Search Configuration (null) (Search Configuration)

Load ask parameters from this configuration. Parameters in the request override parameters from the configuration.

Reasoning (object) or Reasoning options (boolean) (Reasoning options)
Default: false

Reasoning options for the generative model. Set to True to enable default reasoning, False to disable, or provide a Reasoning object for custom options.

Responses

Request samples

Content type
application/json
{
  • "audit_metadata": {
    },
  • "query": "string",
  • "agentic_config_id": "string",
  • "top_k": 20,
  • "filter_expression": {
    },
  • "fields": [ ],
  • "filters": [ ],
  • "keyword_filters": [
    ],
  • "vectorset": "string",
  • "min_score": 0,
  • "features": [
    ],
  • "range_creation_start": "2019-08-24T14:15:22Z",
  • "range_creation_end": "2019-08-24T14:15:22Z",
  • "range_modification_start": "2019-08-24T14:15:22Z",
  • "range_modification_end": "2019-08-24T14:15:22Z",
  • "show": [
    ],
  • "field_type_filter": [
    ],
  • "extracted": [ ],
  • "context": [
    ],
  • "chat_history": [
    ],
  • "extra_context": [
    ],
  • "extra_context_images": [
    ],
  • "query_image": {
    },
  • "highlight": false,
  • "resource_filters": [ ],
  • "prompt": "string",
  • "rank_fusion": "rrf",
  • "reranker": "predict",
  • "citations": true,
  • "citation_threshold": 1,
  • "security": {
    },
  • "show_hidden": false,
  • "rag_strategies": [
    ],
  • "rag_images_strategies": [ ],
  • "debug": false,
  • "generative_model": "string",
  • "generative_model_seed": 0,
  • "max_tokens": 0,
  • "rephrase": false,
  • "chat_history_relevance_threshold": 1,
  • "prefer_markdown": false,
  • "answer_json_schema": {
    },
  • "generate_answer": true,
  • "search_configuration": "string",
  • "reasoning": false
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "reasoning": "string",
  • "answer_json": { },
  • "status": "string",
  • "retrieval_results": {
    },
  • "retrieval_best_matches": [ ],
  • "prequeries": {
    },
  • "learning_id": "",
  • "relations": {
    },
  • "citations": { },
  • "citation_footnote_to_context": {
    },
  • "augmented_context": {
    },
  • "prompt_context": [
    ],
  • "predict_request": { },
  • "metadata": {
    },
  • "consumption": {
    },
  • "error_details": "string",
  • "debug": { }
}

Ask a resource (by slug)

Ask questions to a resource

path Parameters
kbid
required
string (Kbid)
slug
required
string (Slug)
header Parameters
x-show-consumption
boolean (X-Show-Consumption)
Default: false
x-ndb-client
string (NucliaDBClientType)
Default: api
Enum: "api" "widget" "web" "dashboard" "desktop" "chrome_extension"
x-nucliadb-user
string (X-Nucliadb-User)
Default:
x-forwarded-for
string (X-Forwarded-For)
Default:
x-synchronous
boolean (X-Synchronous)
Default: false

When set to true, outputs response as JSON in a non-streaming way. This is slower and requires waiting for entire answer to be ready.

Request Body schema: application/json
required
Audit metadata (object) or Audit metadata (null) (Audit metadata)

A dictionary containing optional audit-specific metadata, such as user_id, environment, or other contextual information. This metadata can be leveraged for filtering and analyzing activity logs in future operations. Each key-value pair represents a piece of metadata relevant to the user's request.

query
required
string (Query) <= 20000 characters

The query to get a generative answer for

Agentic configuration ID (string) or Agentic configuration ID (null) (Agentic configuration ID)

The ID of the agentic configuration to use for this request. If not provided, the default retrieval and generation parameters of the Knowledge Box will be used. If provided, the parameters in the agentic configuration will override the parameters in the request. Note that the query field in the agentic configuration will be ignored, and the query in the request will be used instead.

top_k
integer (Top k) [ 1 .. 200 ]
Default: 20

The top most relevant results to fetch at the retrieval step. The maximum number of results allowed is 200.

FilterExpression (object) or Filter resource by an expression (null) (Filter resource by an expression)

Returns only documents that match this filter expression.Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters This allows building complex filtering expressions and replaces the following parameters:fields, filters, range_*, resource_filters, keyword_filters.

fields
Array of strings (Fields)
Default: []

The list of fields to search in. For instance: a/title to search only on title field. For more details on filtering by field, see: https://docs.nuclia.dev/docs/rag/advanced/search/#search-in-a-specific-field.

Array of Search Filters (strings) or Array of Search Filters (objects) (Search Filters)
Default: []

The list of filters to apply. Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters

Array of Keyword filters (strings) or Array of Keyword filters (objects) (Keyword filters)
Default: []

List of keyword filter expressions to apply to the retrieval step. The text block search will only be performed on the documents that contain the specified keywords. The filters are case-insensitive, and only alphanumeric characters and spaces are allowed. Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters

Vectorset (string) or Vectorset (null) (Vectorset)

Vectors index to perform the search in. If not provided, NucliaDB will use the default one

Minimum score (number) or MinScore (object) or Minimum score (null) (Minimum score)

Minimum score to filter search results. Results with a lower score will be ignored. Accepts either a float or a dictionary with the minimum scores for the bm25 and vector indexes. If a float is provided, it is interpreted as the minimum score for vector index search.

features
Array of strings (Chat features)
Default: ["semantic","keyword"]
Items Enum: "keyword" "relations" "semantic"

Features enabled for the chat endpoint. Semantic search is done if semantic is included. If keyword is included, the results will include matching paragraphs from the bm25 index. If relations is included, a graph of entities related to the answer is returned. paragraphs and vectors are deprecated, please use keyword and semantic instead

Resource creation range start (string) or Resource creation range start (null) (Resource creation range start)

Resources created before this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

Resource creation range end (string) or Resource creation range end (null) (Resource creation range end)

Resources created after this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

Resource modification range start (string) or Resource modification range start (null) (Resource modification range start)

Resources modified before this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

Resource modification range end (string) or Resource modification range end (null) (Resource modification range end)

Resources modified after this date will be filtered out of search results. Datetime are represented as a str in ISO 8601 format, like: 2008-09-15T15:53:00+05:00.

show
Array of strings (Show metadata)
Default: ["basic"]
Items Enum: "basic" "origin" "extra" "relations" "values" "extracted" "errors" "security"

Controls which types of metadata are serialized on resources of search results

field_type_filter
Array of strings (Field type filter)
Default: ["text","file","link","conversation","generic","key_value"]
Items Enum: "text" "file" "link" "conversation" "generic" "key_value"

Define which field types are serialized on resources of search results

extracted
Array of strings (Extracted metadata)
Deprecated
Default: []
Items Enum: "text" "metadata" "shortened_metadata" "large_metadata" "vectors" "link" "file" "question_answers" "relation_vectors"

[Deprecated] Please use GET resource endpoint instead to get extracted metadata

Array of Chat context (deprecated) (objects) or Chat context (deprecated) (null) (Chat context (deprecated))
Deprecated

DEPRECATED! Please, use chat_history instead.

Array of Chat history (objects) or Chat history (null) (Chat history)

Use to rephrase the new LLM query by taking into account the chat conversation history. This will be passed to the LLM so that it is aware of the previous conversation.

Array of Extra query context (strings) or Extra query context (null) (Extra query context)

Additional context that is added to the retrieval context sent to the LLM. It allows extending the chat feature with content that may not be in the Knowledge Box.

Array of Extra query context images (objects) or Extra query context images (null) (Extra query context images)

Additional images added to the retrieval context sent to the LLM." It allows extending the chat feature with content that may not be in the Knowledge Box.

Image (object) or Query image (null) (Query image)

Image that will be used together with the query text for retrieval and then sent to the LLM as part of the context. If a query image is provided, the extra_context_images and rag_images_strategies will be disabled.

highlight
boolean (Highlight)
Default: false

If set to true, the query terms will be highlighted in the results between ... tags

resource_filters
Array of strings (Resources filter)
Default: []

List of resource ids to filter search results for. Only paragraphs from the specified resources will be returned.

Prompts (string) or CustomPrompt (object) or Prompts (null) (Prompts)

Use to customize the prompts given to the generative model. Both system and user prompts can be customized. If a string is provided, it is interpreted as the user prompt.

RankFusionName (string) or Rank fusion (any) (Rank fusion)
Default: "rrf"

Rank fusion algorithm to use to merge results from multiple retrievers (keyword, semantic)

RerankerName (string) or Reranker (any) (Reranker)
Default: "predict"

Reranker let you specify which method you want to use to rerank your results at the end of retrieval

Citations (boolean) or CitationsType (string) or Citations (null) (Citations)

Whether to include citations in the response. If set to None or False, no citations will be computed. If set to True or 'default', citations will be computed after answer generation and send as a separate CitationsGenerativeResponse chunk. If set to 'llm_footnotes', citations will be included in the LLM's response as markdown-styled footnotes. A FootnoteCitationsGenerativeResponse chunk will also be sent to map footnote ids to context keys in the query_context.

Citation Threshold (number) or Citation Threshold (null) (Citation Threshold)

If citations is set to True or 'default', this will be the similarity threshold. Value between 0 and 1, lower values will produce more citations. If not set, it will be set to the optimized threshold found by Nuclia.

RequestSecurity (object) or Security (null) (Security)

Security metadata for the request. Please refer to the documentation for more details on how security works: https://docs.rag.progress.cloud/docs/management/how-to/restrict-access

show_hidden
boolean (Show hidden resources)
Default: false

If set to false (default), excludes hidden resources from search

Array of any (RAG context building strategies)
Default: []

Options for tweaking how the context for the LLM model is crafted:

  • full_resource will add the full text of the matching resources to the context. This strategy cannot be combined with hierarchy, neighbouring_paragraphs, or field_extension.
  • field_extension will add the text of the matching resource's specified fields to the context.
  • hierarchy will add the title and summary text of the parent resource to the context for each matching paragraph.
  • neighbouring_paragraphs will add the sorrounding paragraphs to the context for each matching paragraph.
  • metadata_extension will add the metadata of the matching paragraphs or its resources to the context.
  • prequeries allows to run multiple retrieval queries before the main query and add the results to the context. The results of specific queries can be boosted by the specifying weights.

If empty, the default strategy is used, which simply adds the text of the matching paragraphs to the context.

Array of any (RAG image context building strategies)
Default: []

Options for tweaking how the image based context for the LLM model is crafted:

  • page_image will add the full page image of the matching resources to the context.
  • tables will send the table images for the paragraphs that contain tables and matched the retrieval query.
  • paragraph_image will add the images of the paragraphs that contain images (images for tables are not included). No image strategy is used by default. Note that this is only available for LLM models that support visual inputs. If the model does not support visual inputs, the image strategies will be ignored.
debug
boolean (Debug mode)
Default: false

If set, the response will include some extra metadata for debugging purposes, like the list of queried nodes.

Generative model (string) or Generative model (null) (Generative model)

The generative model to use for the chat endpoint. If not provided, the model configured for the Knowledge Box is used.

Seed for the generative model (integer) or Seed for the generative model (null) (Seed for the generative model)

The seed to use for the generative model for deterministic generation. Only supported by some models.

Maximum LLM tokens to use for the request (integer) or MaxTokens (object) or Maximum LLM tokens to use for the request (null) (Maximum LLM tokens to use for the request)

Use to limit the amount of tokens used in the LLM context and/or for generating the answer. If not provided, the default maximum tokens of the generative model will be used. If an integer is provided, it is interpreted as the maximum tokens for the answer.

rephrase
boolean (Rephrase)
Default: false

Rephrase the query for a more efficient retrieval. This will consume LLM tokens and make the request slower.

Chat History Relevance Threshold (number) or Chat History Relevance Threshold (null) (Chat History Relevance Threshold)

Threshold to determine if the past chat history is relevant to rephrase the user's question. 0 - Always treat previous messages as relevant (always rephrase).1 - Always treat previous messages as irrelevant (never rephrase).Values in between adjust the sensitivity.

prefer_markdown
boolean (Prefer markdown)
Default: false

If set to true, the response will be in markdown format

Answer JSON schema (object) or Answer JSON schema (null) (Answer JSON schema)

Desired JSON schema for the LLM answer. This schema is passed to the LLM so that it answers in a scructured format following the schema. If not provided, textual response is returned. Note that when using this parameter, the answer in the generative response will not be returned in chunks, the whole response text will be returned instead. Using this feature also disables the citations parameter. For maximal accuracy, please include a description for each field of the schema.

generate_answer
boolean (Generate Answer)
Default: true

Whether to generate an answer using the generative model. If set to false, the response will only contain the retrieval results.

Search Configuration (string) or Search Configuration (null) (Search Configuration)

Load ask parameters from this configuration. Parameters in the request override parameters from the configuration.

Reasoning (object) or Reasoning options (boolean) (Reasoning options)
Default: false

Reasoning options for the generative model. Set to True to enable default reasoning, False to disable, or provide a Reasoning object for custom options.

Responses

Request samples

Content type
application/json
{
  • "audit_metadata": {
    },
  • "query": "string",
  • "agentic_config_id": "string",
  • "top_k": 20,
  • "filter_expression": {
    },
  • "fields": [ ],
  • "filters": [ ],
  • "keyword_filters": [
    ],
  • "vectorset": "string",
  • "min_score": 0,
  • "features": [
    ],
  • "range_creation_start": "2019-08-24T14:15:22Z",
  • "range_creation_end": "2019-08-24T14:15:22Z",
  • "range_modification_start": "2019-08-24T14:15:22Z",
  • "range_modification_end": "2019-08-24T14:15:22Z",
  • "show": [
    ],
  • "field_type_filter": [
    ],
  • "extracted": [ ],
  • "context": [
    ],
  • "chat_history": [
    ],
  • "extra_context": [
    ],
  • "extra_context_images": [
    ],
  • "query_image": {
    },
  • "highlight": false,
  • "resource_filters": [ ],
  • "prompt": "string",
  • "rank_fusion": "rrf",
  • "reranker": "predict",
  • "citations": true,
  • "citation_threshold": 1,
  • "security": {
    },
  • "show_hidden": false,
  • "rag_strategies": [
    ],
  • "rag_images_strategies": [ ],
  • "debug": false,
  • "generative_model": "string",
  • "generative_model_seed": 0,
  • "max_tokens": 0,
  • "rephrase": false,
  • "chat_history_relevance_threshold": 1,
  • "prefer_markdown": false,
  • "answer_json_schema": {
    },
  • "generate_answer": true,
  • "search_configuration": "string",
  • "reasoning": false
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "reasoning": "string",
  • "answer_json": { },
  • "status": "string",
  • "retrieval_results": {
    },
  • "retrieval_best_matches": [ ],
  • "prequeries": {
    },
  • "learning_id": "",
  • "relations": {
    },
  • "citations": { },
  • "citation_footnote_to_context": {
    },
  • "augmented_context": {
    },
  • "prompt_context": [
    ],
  • "predict_request": { },
  • "metadata": {
    },
  • "consumption": {
    },
  • "error_details": "string",
  • "debug": { }
}

MCP

Model Context Protocol endpoints.

Mcp Handler

path Parameters
kbid
required
string (Kbid)
header Parameters
x-ndb-client
string (NucliaDBClientType)
Default: api
Enum: "api" "widget" "web" "dashboard" "desktop" "chrome_extension"
x-nucliadb-user
string (X-Nucliadb-User)
Default:
x-forwarded-for
string (X-Forwarded-For)
Default:

Responses

Response samples

Content type
application/json
null

Mcp Handler

path Parameters
kbid
required
string (Kbid)
header Parameters
x-ndb-client
string (NucliaDBClientType)
Default: api
Enum: "api" "widget" "web" "dashboard" "desktop" "chrome_extension"
x-nucliadb-user
string (X-Nucliadb-User)
Default:
x-forwarded-for
string (X-Forwarded-For)
Default:

Responses

Response samples

Content type
application/json
null

Sources

Agentic source endpoints.

List sources

path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Create a source

path Parameters
kbid
required
string (Kbid)
source_id
required
string (Source Id)
Request Body schema: application/json
required
Any of
type
string (Type)
Default: "nucliadb"
Value: "nucliadb"
Description (string) or Description (null) (Description)
FilterExpression (object) or Filter expression (null) (Filter expression)

Filter expression to narrow NucliaDB search results

Array of Labels (strings) or Labels (null) (Labels)

Label filters to restrict which resources are searched

Array of Resource filters (strings) or Resource filters (null) (Resource filters)

Additional resource-level filters passed to the NucliaDB search API

Responses

Request samples

Content type
application/json
Example
{
  • "type": "nucliadb",
  • "description": "string",
  • "filter_expression": {
    },
  • "labels": [
    ],
  • "resource_filters": [
    ]
}

Response samples

Content type
application/json
null

Get a source

path Parameters
kbid
required
string (Kbid)
source_id
required
string (Source Id)

Responses

Response samples

Content type
application/json
Example
{
  • "type": "nucliadb",
  • "description": "string",
  • "filter_expression": {
    },
  • "labels": [
    ],
  • "resource_filters": [
    ]
}

Update a source

path Parameters
kbid
required
string (Kbid)
source_id
required
string (Source Id)
Request Body schema: application/json
required
Any of
type
string (Type)
Default: "nucliadb"
Value: "nucliadb"
Description (string) or Description (null) (Description)
FilterExpression (object) or Filter expression (null) (Filter expression)

Filter expression to narrow NucliaDB search results

Array of Labels (strings) or Labels (null) (Labels)

Label filters to restrict which resources are searched

Array of Resource filters (strings) or Resource filters (null) (Resource filters)

Additional resource-level filters passed to the NucliaDB search API

Responses

Request samples

Content type
application/json
Example
{
  • "type": "nucliadb",
  • "description": "string",
  • "filter_expression": {
    },
  • "labels": [
    ],
  • "resource_filters": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete a source

path Parameters
kbid
required
string (Kbid)
source_id
required
string (Source Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}