Skip to main content
API docs by Redocly

NucliaDB REST API (v1)

API reference for the NucliaDB, covering all the endpoints related to pushing or searching contents.

Resources

Knowledge Box resource endpoints

Get Resource (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
query Parameters
show
Array of strings (Show)
Default: "basic"
Items Enum: "basic" "origin" "extra" "relations" "values" "extracted" "errors" "security"
field_type
Array of strings (Field Type)
Default: "text&field_type=file&field_type=link&field_type=conversation&field_type=generic"
Items Enum: "text" "file" "link" "conversation" "generic"
extracted
Array of strings (Extracted)
Default: "text&extracted=metadata&extracted=link&extracted=file"
Items Enum: "text" "metadata" "shortened_metadata" "large_metadata" "vectors" "link" "file" "question_answers"
header Parameters
x-nucliadb-user
string (X-Nucliadb-User)
Default:
x-forwarded-for
string (X-Forwarded-For)
Default:

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "slug": "string",
  • "title": "string",
  • "summary": "string",
  • "icon": "string",
  • "thumbnail": "string",
  • "metadata": {
    },
  • "usermetadata": {
    },
  • "fieldmetadata": [
    ],
  • "computedmetadata": {
    },
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "last_seqid": 0,
  • "last_account_seq": 0,
  • "queue": "private",
  • "origin": {
    },
  • "extra": {
    },
  • "relations": [
    ],
  • "data": {
    },
  • "security": {
    }
}

Modify Resource (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
header Parameters
x-skip-store
boolean (X-Skip-Store)
Default: false

If set to true, file fields will not be saved in the blob storage. They will only be sent to process.

x-nucliadb-user
string (X-Nucliadb-User)
Default:
Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Summary (string) or Summary (null) (Summary)
Slug (string) or Slug (null) (Slug)

The slug is the user-defined id for the resource

Thumbnail (string) or Thumbnail (null) (Thumbnail)
InputMetadata (object) or null
UserMetadata (object) or null
Array of Fieldmetadata (objects) or Fieldmetadata (null) (Fieldmetadata)
Origin (object) or null
Extra (object) or null
object (Files)
Default: {}

Dictionary of file fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Links)
Default: {}

Dictionary of link fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Texts)
Default: {}

Dictionary of text fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Conversations)
Default: {}

Dictionary of conversation fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

PushProcessingOptions (object) or null
Default: {"ml_text":true}
ResourceSecurity (object) or Security (null) (Security)

Security metadata for the resource. It can be used to have fine-grained control over who can access the resource.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "summary": "string",
  • "slug": "string",
  • "thumbnail": "string",
  • "metadata": {
    },
  • "usermetadata": {
    },
  • "fieldmetadata": [
    ],
  • "origin": {
    },
  • "extra": {
    },
  • "files": { },
  • "links": { },
  • "texts": { },
  • "conversations": { },
  • "processing_options": {
    },
  • "security": {
    }
}

Response samples

Content type
application/json
{
  • "seqid": 0
}

Delete Resource (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)

Responses

Response samples

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

Reindex Resource (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
query Parameters
reindex_vectors
boolean (Reindex Vectors)
Default: false

Responses

Response samples

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

Reprocess resource (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
header Parameters
x-nucliadb-user
string (X-Nucliadb-User)
Default:

Responses

Response samples

Content type
application/json
{
  • "seqid": 0
}

List Resources

List of resources of a knowledgebox

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
query Parameters
page
integer (Page)
Default: 0

Requested page number (0-based)

size
integer (Size)
Default: 20

Page size

Responses

Response samples

Content type
application/json
{
  • "resources": [
    ],
  • "pagination": {
    }
}

Create Resource

Create a new Resource in a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
header Parameters
x-skip-store
boolean (X-Skip-Store)
Default: false

If set to true, file fields will not be saved in the blob storage. They will only be sent to process.

Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Summary (string) or Summary (null) (Summary)
Slug (string) or Slug (null) (Slug)

The slug is the user-defined id for the resource

Icon (string) or Icon (null) (Icon)
Thumbnail (string) or Thumbnail (null) (Thumbnail)
InputMetadata (object) or null
UserMetadata (object) or null
Array of Fieldmetadata (objects) or Fieldmetadata (null) (Fieldmetadata)
Origin (object) or null
Extra (object) or null
object (Files)
Default: {}

Dictionary of file fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Links)
Default: {}

Dictionary of link fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Texts)
Default: {}

Dictionary of text fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Conversations)
Default: {}

Dictionary of conversation fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

PushProcessingOptions (object) or null
Default: {"ml_text":true}
ResourceSecurity (object) or Security (null) (Security)

Security metadata for the resource. It can be used to have fine-grained control over who can access the resource.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "summary": "string",
  • "slug": "string",
  • "icon": "string",
  • "thumbnail": "string",
  • "metadata": {
    },
  • "usermetadata": {
    },
  • "fieldmetadata": [
    ],
  • "origin": {
    },
  • "extra": {
    },
  • "files": { },
  • "links": { },
  • "texts": { },
  • "conversations": { },
  • "processing_options": {
    },
  • "security": {
    }
}

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "elapsed": 0,
  • "seqid": 0
}

Get Resource (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
query Parameters
show
Array of strings (Show)
Default: "basic"
Items Enum: "basic" "origin" "extra" "relations" "values" "extracted" "errors" "security"
field_type
Array of strings (Field Type)
Default: "text&field_type=file&field_type=link&field_type=conversation&field_type=generic"
Items Enum: "text" "file" "link" "conversation" "generic"
extracted
Array of strings (Extracted)
Default: "text&extracted=metadata&extracted=link&extracted=file"
Items Enum: "text" "metadata" "shortened_metadata" "large_metadata" "vectors" "link" "file" "question_answers"
header Parameters
x-nucliadb-user
string (X-Nucliadb-User)
Default:
x-forwarded-for
string (X-Forwarded-For)
Default:

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "slug": "string",
  • "title": "string",
  • "summary": "string",
  • "icon": "string",
  • "thumbnail": "string",
  • "metadata": {
    },
  • "usermetadata": {
    },
  • "fieldmetadata": [
    ],
  • "computedmetadata": {
    },
  • "created": "2019-08-24T14:15:22Z",
  • "modified": "2019-08-24T14:15:22Z",
  • "last_seqid": 0,
  • "last_account_seq": 0,
  • "queue": "private",
  • "origin": {
    },
  • "extra": {
    },
  • "relations": [
    ],
  • "data": {
    },
  • "security": {
    }
}

Modify Resource (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
header Parameters
x-skip-store
boolean (X-Skip-Store)
Default: false

If set to true, file fields will not be saved in the blob storage. They will only be sent to process.

x-nucliadb-user
string (X-Nucliadb-User)
Default:
Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Summary (string) or Summary (null) (Summary)
Slug (string) or Slug (null) (Slug)

The slug is the user-defined id for the resource

Thumbnail (string) or Thumbnail (null) (Thumbnail)
InputMetadata (object) or null
UserMetadata (object) or null
Array of Fieldmetadata (objects) or Fieldmetadata (null) (Fieldmetadata)
Origin (object) or null
Extra (object) or null
object (Files)
Default: {}

Dictionary of file fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Links)
Default: {}

Dictionary of link fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Texts)
Default: {}

Dictionary of text fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Conversations)
Default: {}

Dictionary of conversation fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

PushProcessingOptions (object) or null
Default: {"ml_text":true}
ResourceSecurity (object) or Security (null) (Security)

Security metadata for the resource. It can be used to have fine-grained control over who can access the resource.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "summary": "string",
  • "slug": "string",
  • "thumbnail": "string",
  • "metadata": {
    },
  • "usermetadata": {
    },
  • "fieldmetadata": [
    ],
  • "origin": {
    },
  • "extra": {
    },
  • "files": { },
  • "links": { },
  • "texts": { },
  • "conversations": { },
  • "processing_options": {
    },
  • "security": {
    }
}

Response samples

Content type
application/json
{
  • "seqid": 0
}

Delete Resource (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)

Responses

Response samples

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

Reindex Resource (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
query Parameters
reindex_vectors
boolean (Reindex Vectors)
Default: false

Responses

Response samples

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

Reprocess resource (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
header Parameters
x-nucliadb-user
string (X-Nucliadb-User)
Default:

Responses

Response samples

Content type
application/json
{
  • "seqid": 0
}

Resource fields

Knowledge Box resource's fields endpoints

Upload binary file on a Resource (by id)

Upload a file as a field on an existing resource, if the field exists will return a conflict (419)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
path_rid
required
string (Path Rid)
field
required
string (Field) ^[a-zA-Z0-9:_-]+$
header Parameters
Array of X-Filename (strings) or X-Filename (null) (X-Filename)
Array of X-Password (strings) or X-Password (null) (X-Password)
Array of X-Language (strings) or X-Language (null) (X-Language)
Array of X-Md5 (strings) or X-Md5 (null) (X-Md5)

Responses

Response samples

Content type
application/json
{
  • "seqid": 0,
  • "uuid": "string",
  • "field_id": "string"
}

Add resource conversation field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
required
Array of objects (Messages)
Default: []
Array
Timestamp (string) or Timestamp (null) (Timestamp)
Who (string) or Who (null) (Who)
to
Array of strings (To)
Default: []
required
object (InputMessageContent)
ident
required
string (Ident)
MessageType (string) or null

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "seqid": 0
}

Download conversation binary field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_id
required
string (Field Id)
message_id
required
string (Message Id)
file_num
required
integer (File Num)

Responses

Response samples

Content type
application/json
null

Append messages to conversation field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
required
Array
Timestamp (string) or Timestamp (null) (Timestamp)
Who (string) or Who (null) (Who)
to
Array of strings (To)
Default: []
required
object (InputMessageContent)
ident
required
string (Ident)
MessageType (string) or null

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "seqid": 0
}

Add resource file field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
header Parameters
x-skip-store
boolean (X-Skip-Store)
Default: false

If set to true, file fields will not be saved in the blob storage. They will only be sent to process.

Request Body schema: application/json
required
Language (string) or Language (null) (Language)
Password (string) or Password (null) (Password)
required
object (File)

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "password": "string",
  • "file": {
    }
}

Response samples

Content type
application/json
{
  • "seqid": 0
}

Download field binary field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_id
required
string (Field Id)
query Parameters
inline
boolean (Inline)
Default: false

Responses

Response samples

Content type
application/json
null

Reprocess file field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
header Parameters
x-nucliadb-user
string (X-Nucliadb-User)
Default:
X-File-Password (string) or X-File-Password (null) (X-File-Password)

If a file is password protected, the password must be provided here for the file to be processed

Responses

Response samples

Content type
application/json
{
  • "seqid": 0
}

Add resource link field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
required
Headers (object) or Headers (null) (Headers)
Default: {}
Cookies (object) or Cookies (null) (Cookies)
Default: {}
uri
required
string (Uri)
Language (string) or Language (null) (Language)
Localstorage (object) or Localstorage (null) (Localstorage)
Default: {}
Css Selector (string) or Css Selector (null) (Css Selector)
Xpath (string) or Xpath (null) (Xpath)

Responses

Request samples

Content type
application/json
{
  • "headers": { },
  • "cookies": { },
  • "uri": "string",
  • "language": "string",
  • "localstorage": { },
  • "css_selector": "string",
  • "xpath": "string"
}

Response samples

Content type
application/json
{
  • "seqid": 0
}

Add resource text field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
required
body
required
string (Body) <= 2097152 characters

The text body. The format of the text should be specified in the format field. The sum of all text fields in the request may not exceed 2MB. If you need to store more text, consider using a file field instead or splitting into multiple requests for each text field.

format
string (TextFormat)
Default: "PLAIN"
Enum: "PLAIN" "HTML" "RST" "MARKDOWN" "JSON" "KEEP_MARKDOWN"

The format of the text.

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "format": "PLAIN"
}

Response samples

Content type
application/json
{
  • "seqid": 0
}

Get Resource field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_type
required
string (FieldTypeName)
Enum: "text" "file" "link" "conversation" "generic"

This map assumes that both values and extracted data field containers use the same names for its fields. See models.ResourceFieldValues and models.ResourceFieldExtractedData

field_id
required
string (Field Id)
query Parameters
show
Array of strings (Show)
Default: "value"
Items Enum: "value" "extracted" "error"
extracted
Array of strings (Extracted)
Default: "text&extracted=metadata&extracted=link&extracted=file"
Items Enum: "text" "metadata" "shortened_metadata" "large_metadata" "vectors" "link" "file" "question_answers"
Page (string) or Page (integer) (Page)
Default: "last"

Responses

Response samples

Content type
application/json
{
  • "field_type": "text",
  • "field_id": "string",
  • "value": null,
  • "extracted": {
    },
  • "error": {
    }
}

Delete Resource field (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_type
required
string (FieldTypeName)
Enum: "text" "file" "link" "conversation" "generic"

This map assumes that both values and extracted data field containers use the same names for its fields. See models.ResourceFieldValues and models.ResourceFieldExtractedData

field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$

Responses

Response samples

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

Download extracted binary file (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field_type
required
string (FieldTypeName)
Enum: "text" "file" "link" "conversation" "generic"

This map assumes that both values and extracted data field containers use the same names for its fields. See models.ResourceFieldValues and models.ResourceFieldExtractedData

field_id
required
string (Field Id)
download_field
required
string (Download Field)

Responses

Response samples

Content type
application/json
null

Add resource conversation field (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
required
Array of objects (Messages)
Default: []
Array
Timestamp (string) or Timestamp (null) (Timestamp)
Who (string) or Who (null) (Who)
to
Array of strings (To)
Default: []
required
object (InputMessageContent)
ident
required
string (Ident)
MessageType (string) or null

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "seqid": 0
}

Download conversation binary field (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_id
required
string (Field Id)
message_id
required
string (Message Id)
file_num
required
integer (File Num)

Responses

Response samples

Content type
application/json
null

Append messages to conversation field (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
required
Array
Timestamp (string) or Timestamp (null) (Timestamp)
Who (string) or Who (null) (Who)
to
Array of strings (To)
Default: []
required
object (InputMessageContent)
ident
required
string (Ident)
MessageType (string) or null

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "seqid": 0
}

Add resource file field (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
header Parameters
x-skip-store
boolean (X-Skip-Store)
Default: false

If set to true, file fields will not be saved in the blob storage. They will only be sent to process.

Request Body schema: application/json
required
Language (string) or Language (null) (Language)
Password (string) or Password (null) (Password)
required
object (File)

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "password": "string",
  • "file": {
    }
}

Response samples

Content type
application/json
{
  • "seqid": 0
}

Download field binary field (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_id
required
string (Field Id)
query Parameters
inline
boolean (Inline)
Default: false

Responses

Response samples

Content type
application/json
null

Upload binary file on a Resource (by slug)

Upload a file as a field on an existing resource, if the field exists will return a conflict (419)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field
required
string (Field) ^[a-zA-Z0-9:_-]+$
header Parameters
Array of X-Filename (strings) or X-Filename (null) (X-Filename)
Array of X-Password (strings) or X-Password (null) (X-Password)
Array of X-Language (strings) or X-Language (null) (X-Language)
Array of X-Md5 (strings) or X-Md5 (null) (X-Md5)

Responses

Response samples

Content type
application/json
{
  • "seqid": 0,
  • "uuid": "string",
  • "field_id": "string"
}

Add resource link field (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
required
Headers (object) or Headers (null) (Headers)
Default: {}
Cookies (object) or Cookies (null) (Cookies)
Default: {}
uri
required
string (Uri)
Language (string) or Language (null) (Language)
Localstorage (object) or Localstorage (null) (Localstorage)
Default: {}
Css Selector (string) or Css Selector (null) (Css Selector)
Xpath (string) or Xpath (null) (Xpath)

Responses

Request samples

Content type
application/json
{
  • "headers": { },
  • "cookies": { },
  • "uri": "string",
  • "language": "string",
  • "localstorage": { },
  • "css_selector": "string",
  • "xpath": "string"
}

Response samples

Content type
application/json
{
  • "seqid": 0
}

Add resource text field (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
required
body
required
string (Body) <= 2097152 characters

The text body. The format of the text should be specified in the format field. The sum of all text fields in the request may not exceed 2MB. If you need to store more text, consider using a file field instead or splitting into multiple requests for each text field.

format
string (TextFormat)
Default: "PLAIN"
Enum: "PLAIN" "HTML" "RST" "MARKDOWN" "JSON" "KEEP_MARKDOWN"

The format of the text.

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "format": "PLAIN"
}

Response samples

Content type
application/json
{
  • "seqid": 0
}

Get Resource field (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_type
required
string (FieldTypeName)
Enum: "text" "file" "link" "conversation" "generic"

This map assumes that both values and extracted data field containers use the same names for its fields. See models.ResourceFieldValues and models.ResourceFieldExtractedData

field_id
required
string (Field Id)
query Parameters
show
Array of strings (Show)
Default: "value"
Items Enum: "value" "extracted" "error"
extracted
Array of strings (Extracted)
Default: "text&extracted=metadata&extracted=link&extracted=file"
Items Enum: "text" "metadata" "shortened_metadata" "large_metadata" "vectors" "link" "file" "question_answers"
Page (string) or Page (integer) (Page)
Default: "last"

Responses

Response samples

Content type
application/json
{
  • "field_type": "text",
  • "field_id": "string",
  • "value": null,
  • "extracted": {
    },
  • "error": {
    }
}

Delete Resource field (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_type
required
string (FieldTypeName)
Enum: "text" "file" "link" "conversation" "generic"

This map assumes that both values and extracted data field containers use the same names for its fields. See models.ResourceFieldValues and models.ResourceFieldExtractedData

field_id
required
string (Field Id) ^[a-zA-Z0-9:_-]+$

Responses

Response samples

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

Download extracted binary file (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field_type
required
string (FieldTypeName)
Enum: "text" "file" "link" "conversation" "generic"

This map assumes that both values and extracted data field containers use the same names for its fields. See models.ResourceFieldValues and models.ResourceFieldExtractedData

field_id
required
string (Field Id)
download_field
required
string (Download Field)

Responses

Response samples

Content type
application/json
null

Resource field TUS uploads

Endpoints for TUS Resumable File Uploads protocol. This endpoints are compliant with the TUS protocol. You're not suposed to uses this endpoints directly, but use a TUS client in your language.

We also support the Creation extension on top of the Core TUS protocol

See https://tus.io/ for more info.

Create new upload on a Resource (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
path_rid
required
string (Path Rid)
field
required
string (Field) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
Any of
Title (string) or Title (null) (Title)
Summary (string) or Summary (null) (Summary)
Slug (string) or Slug (null) (Slug)

The slug is the user-defined id for the resource

Icon (string) or Icon (null) (Icon)
Thumbnail (string) or Thumbnail (null) (Thumbnail)
InputMetadata (object) or null
UserMetadata (object) or null
Array of Fieldmetadata (objects) or Fieldmetadata (null) (Fieldmetadata)
Origin (object) or null
Extra (object) or null
object (Files)
Default: {}

Dictionary of file fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Links)
Default: {}

Dictionary of link fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Texts)
Default: {}

Dictionary of text fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Conversations)
Default: {}

Dictionary of conversation fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

PushProcessingOptions (object) or null
Default: {"ml_text":true}
ResourceSecurity (object) or Security (null) (Security)

Security metadata for the resource. It can be used to have fine-grained control over who can access the resource.

Responses

Request samples

Content type
application/json
Example
{
  • "title": "string",
  • "summary": "string",
  • "slug": "string",
  • "icon": "string",
  • "thumbnail": "string",
  • "metadata": {
    },
  • "usermetadata": {
    },
  • "fieldmetadata": [
    ],
  • "origin": {
    },
  • "extra": {
    },
  • "files": { },
  • "links": { },
  • "texts": { },
  • "conversations": { },
  • "processing_options": {
    },
  • "security": {
    }
}

Response samples

Content type
application/json
null

Upload information

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
path_rid
required
string (Path Rid)
field
required
string (Field) ^[a-zA-Z0-9:_-]+$
upload_id
required
string (Upload Id)

Responses

Response samples

Content type
application/json
null

Upload data on a Resource (by id)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
field
required
string (Field) ^[a-zA-Z0-9:_-]+$
upload_id
required
string (Upload Id)

Responses

Response samples

Content type
application/json
null

Create new upload on a Resource (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field
required
string (Field) ^[a-zA-Z0-9:_-]+$
Request Body schema: application/json
Any of
Title (string) or Title (null) (Title)
Summary (string) or Summary (null) (Summary)
Slug (string) or Slug (null) (Slug)

The slug is the user-defined id for the resource

Icon (string) or Icon (null) (Icon)
Thumbnail (string) or Thumbnail (null) (Thumbnail)
InputMetadata (object) or null
UserMetadata (object) or null
Array of Fieldmetadata (objects) or Fieldmetadata (null) (Fieldmetadata)
Origin (object) or null
Extra (object) or null
object (Files)
Default: {}

Dictionary of file fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Links)
Default: {}

Dictionary of link fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Texts)
Default: {}

Dictionary of text fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Conversations)
Default: {}

Dictionary of conversation fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

PushProcessingOptions (object) or null
Default: {"ml_text":true}
ResourceSecurity (object) or Security (null) (Security)

Security metadata for the resource. It can be used to have fine-grained control over who can access the resource.

Responses

Request samples

Content type
application/json
Example
{
  • "title": "string",
  • "summary": "string",
  • "slug": "string",
  • "icon": "string",
  • "thumbnail": "string",
  • "metadata": {
    },
  • "usermetadata": {
    },
  • "fieldmetadata": [
    ],
  • "origin": {
    },
  • "extra": {
    },
  • "files": { },
  • "links": { },
  • "texts": { },
  • "conversations": { },
  • "processing_options": {
    },
  • "security": {
    }
}

Response samples

Content type
application/json
null

Upload data on a Resource (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field
required
string (Field) ^[a-zA-Z0-9:_-]+$
upload_id
required
string (Upload Id)

Responses

Response samples

Content type
application/json
null

Upload information

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
rslug
required
string (Rslug)
field
required
string (Field) ^[a-zA-Z0-9:_-]+$
upload_id
required
string (Upload Id)

Responses

Response samples

Content type
application/json
null

Knowledge Boxes

NucliaDB Knowledge Box endpoints

NOTE:

Except for getting a Knowledge box or listing Knowledge boxes, the rest of operations may be not available in your NucliaDB instance. Creating and managing Knowledge Boxes directly from NucliaDB is available only on standalone usage. If you have a NucliaDB Cloud or a NucliaDB On-prem, you need to manage them from the global API.

Get Knowledge Box (by slug)

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • MANAGER
  • READER
path Parameters
slug
required
string (Slug)

Responses

Response samples

Content type
application/json
{
  • "slug": "string",
  • "uuid": "string",
  • "config": {
    },
  • "model": {
    }
}

Get Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • MANAGER
  • READER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
{
  • "slug": "string",
  • "uuid": "string",
  • "config": {
    },
  • "model": {
    }
}

Knowledgebox Models Configuration

Current configuration of models assigned to a knowledgebox

path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
{
  • "semantic_model": "string",
  • "anonymization_model": "string",
  • "generative_model": "string",
  • "ner_model": "string",
  • "semantic_vector_similarity": "string",
  • "semantic_vector_size": 0
}

Create Knowledge Box models configuration

Create configuration of models assigned to a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

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

Knowledgebox Models Configuration

Current configuration of models assigned to a knowledgebox

path Parameters
kbid
required
string (Kbid)
Request Body schema: application/json
required
anonymization_model
string (AnonimizationModel)
Default: "disabled"
Enum: "disabled" "multilingual"

An enumeration.

generative_model
string (GenerativeModel)
Default: "chatgpt"
Enum: "generative-multilingual-2023" "chatgpt"

An enumeration.

ner_model
string (NERModel)
Default: "multilingual"
Value: "multilingual"

An enumeration.

Responses

Request samples

Content type
application/json
{
  • "anonymization_model": "disabled",
  • "generative_model": "chatgpt",
  • "ner_model": "multilingual"
}

Response samples

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

Knowledgebox Counters

Summary of amount of different things inside a knowledgebox

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
  • MANAGER
path Parameters
kbid
required
string (Kbid)
query Parameters
debug
boolean (Debug mode)
Default: false

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

Responses

Response samples

Content type
application/json
{
  • "resources": 0,
  • "paragraphs": 0,
  • "fields": 0,
  • "sentences": 0,
  • "shards": [
    ],
  • "index_size": 0
}

Start an export of a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • MANAGER
  • WRITER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
{
  • "export_id": "string"
}

Download a Knowledge Box export

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • MANAGER
  • READER
path Parameters
kbid
required
string (Kbid)
export_id
required
string (Export Id)

Responses

Response samples

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

Get the status of a Knowledge Box Export

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • MANAGER
  • READER
path Parameters
kbid
required
string (Kbid)
export_id
required
string (Export Id)

Responses

Response samples

Content type
application/json
{
  • "status": "scheduled",
  • "total": 0,
  • "processed": 0,
  • "retries": 0
}

Feedback avalaible months

List of months within the last year with feedback data

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
null

Download feedback of a Knowledge Box

Download the feedback of a particular month in a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
month
required
string (Month)

Responses

Response samples

Content type
application/json
null

Start an import to a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • MANAGER
  • WRITER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
{
  • "import_id": "string"
}

Get the status of a Knowledge Box Import

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • MANAGER
  • READER
path Parameters
kbid
required
string (Kbid)
import_id
required
string (Import Id)

Responses

Response samples

Content type
application/json
{
  • "status": "scheduled",
  • "total": 0,
  • "processed": 0,
  • "retries": 0
}

Upload binary file on a Knowledge Box

Upload a file onto a Knowledge Box, field id will be file and rid will be autogenerated.

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
header Parameters
Array of X-Filename (strings) or X-Filename (null) (X-Filename)
Array of X-Password (strings) or X-Password (null) (X-Password)
Array of X-Language (strings) or X-Language (null) (X-Language)
Array of X-Md5 (strings) or X-Md5 (null) (X-Md5)

Responses

Response samples

Content type
application/json
{
  • "seqid": 0,
  • "uuid": "string",
  • "field_id": "string"
}

Learning Configuration Schema

Get jsonschema definition for learning_configuration field of knowledgebox creation payload

Responses

Response samples

Content type
application/json
{ }

Knowledge Box TUS uploads

Endpoints for TUS Resumable File Uploads protocol. This endpoints are compliant with the TUS protocol. It is usually preferable to use them through a TUS client library in your language.

We also support the Creation extension on top of the Core TUS protocol

See https://tus.io/ for more info.

Create new upload on a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
Request Body schema: application/json
Any of
Title (string) or Title (null) (Title)
Summary (string) or Summary (null) (Summary)
Slug (string) or Slug (null) (Slug)

The slug is the user-defined id for the resource

Icon (string) or Icon (null) (Icon)
Thumbnail (string) or Thumbnail (null) (Thumbnail)
InputMetadata (object) or null
UserMetadata (object) or null
Array of Fieldmetadata (objects) or Fieldmetadata (null) (Fieldmetadata)
Origin (object) or null
Extra (object) or null
object (Files)
Default: {}

Dictionary of file fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Links)
Default: {}

Dictionary of link fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Texts)
Default: {}

Dictionary of text fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

object (Conversations)
Default: {}

Dictionary of conversation fields to be added to the resource. The keys correspond to the field id, and must comply with the regex: ^[a-zA-Z0-9:_-]+$

PushProcessingOptions (object) or null
Default: {"ml_text":true}
ResourceSecurity (object) or Security (null) (Security)

Security metadata for the resource. It can be used to have fine-grained control over who can access the resource.

Responses

Request samples

Content type
application/json
Example
{
  • "title": "string",
  • "summary": "string",
  • "slug": "string",
  • "icon": "string",
  • "thumbnail": "string",
  • "metadata": {
    },
  • "usermetadata": {
    },
  • "fieldmetadata": [
    ],
  • "origin": {
    },
  • "extra": {
    },
  • "files": { },
  • "links": { },
  • "texts": { },
  • "conversations": { },
  • "processing_options": {
    },
  • "security": {
    }
}

Response samples

Content type
application/json
null

TUS Server information

path Parameters
kbid
required
string (Kbid)
query Parameters
Rid (string) or Rid (null) (Rid)
Rslug (string) or Rslug (null) (Rslug)
Upload Id (string) or Upload Id (null) (Upload Id)
Field (string) or Field (null) (Field)

Responses

Response samples

Content type
application/json
null

Upload data on a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
upload_id
required
string (Upload Id)

Responses

Response samples

Content type
application/json
null

Upload information

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
upload_id
required
string (Upload Id)

Responses

Response samples

Content type
application/json
null

Knowledge Box Services

NucliaDB labels & entities endpoints

Get Knowledge Box Custom Synonyms

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
{
  • "synonyms": {
    }
}

Set Knowledge Box Custom Synonyms

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
Request Body schema: application/json
required
required
object (Synonyms)
property name*
additional property
Array of strings

Responses

Request samples

Content type
application/json
{
  • "synonyms": {
    }
}

Response samples

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

Delete Knowledge Box Custom Synonyms

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

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

Get a Knowledge Box Entities Group

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
group
required
string (Group)

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "color": "string",
  • "custom": false,
  • "entities": { }
}

Update Knowledge Box Entities Group

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
group
required
string (Group)
Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Color (string) or Color (null) (Color)
object (Add)
Default: {}
object (Update)
Default: {}
delete
Array of strings (Delete)
Default: []

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "color": "string",
  • "add": { },
  • "update": { },
  • "delete": [ ]
}

Response samples

Content type
application/json
null

Delete Knowledge Box Entities

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
group
required
string (Group)

Responses

Response samples

Content type
application/json
null

Get Knowledge Box Entities

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
query Parameters
show_entities
boolean (Show Entities)
Default: false

Responses

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "groups": { }
}

Create Knowledge Box Entities Group

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
Request Body schema: application/json
required
group
required
string (Group)
object (Entities)
Default: {}
Title (string) or Title (null) (Title)
Color (string) or Color (null) (Color)

Responses

Request samples

Content type
application/json
{
  • "group": "string",
  • "entities": { },
  • "title": "string",
  • "color": "string"
}

Response samples

Content type
application/json
null

Get a Knowledge Box Label Set

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
labelset
required
string (Labelset)

Responses

Response samples

Content type
application/json
{
  • "title": "no title",
  • "color": "blue",
  • "multiple": true,
  • "kind": [ ],
  • "labels": [ ]
}

Set Knowledge Box Labels

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
labelset
required
string (Labelset)
Request Body schema: application/json
required
Title (string) or Title (null) (Title)
Default: "no title"
Color (string) or Color (null) (Color)
Default: "blue"
multiple
boolean (Multiple)
Default: true
kind
Array of strings (Kind)
Default: []
Items Enum: "RESOURCES" "PARAGRAPHS" "SENTENCES" "SELECTIONS"
Array of objects (Labels)
Default: []

Responses

Request samples

Content type
application/json
{
  • "title": "no title",
  • "color": "blue",
  • "multiple": true,
  • "kind": [ ],
  • "labels": [ ]
}

Response samples

Content type
application/json
null

Delete Knowledge Box Label

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • WRITER
path Parameters
kbid
required
string (Kbid)
labelset
required
string (Labelset)

Responses

Response samples

Content type
application/json
null

Get Knowledge Box Label Sets

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "labelsets": { }
}

Knowledge Box Notifications Stream

Provides a stream of activity notifications for the given Knowledge Box. The stream will be automatically closed after 2 minutes.

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
null

Knowledge Box Processing Status

Provides the status of the processing of the given Knowledge Box.

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
query Parameters
Cursor (string) or Cursor (null) (Cursor)
Scheduled (boolean) or Scheduled (null) (Scheduled)
limit
integer (Limit)
Default: 20

Responses

Response samples

Content type
application/json
{
  • "results": [ ],
  • "cursor": "string"
}

Models

Models API

Get model metadata

Get metadata for a particular model

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
model_id
required
string (Model Id)

Responses

Response samples

Content type
application/json
null

Get available models

Get available models

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
null

Download the Knowledege Box model

Download the trained model or any other generated file as a result of a training task on a Knowledge Box.

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
model_id
required
string (Model Id)
filename
required
string (Filename)

Responses

Response samples

Content type
application/json
null

Learning configuration schema

Get jsonschema definition to update the learning_configuration of your Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)

Responses

Response samples

Content type
application/json
null

Search

Search API

Ask Knowledge Box

Ask questions on a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
header Parameters
x-ndb-client
string (X-Ndb-Client)
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
query
required
string (Query)

The query to get a generative answer for

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/docs/using/search/#search-in-a-specific-field

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

The list of filters to apply. Filtering examples can be found here: https://docs.nuclia.dev/docs/docs/using/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: ["vectors","paragraphs","relations"]
Items Enum: "vectors" "paragraphs" "relations"

Features enabled for the chat endpoint. Semantic search is done if vectors is included. If paragraphs 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.

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"]
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

shards
Array of strings (Shards)
Default: []

The list of shard replicas to search in. If empty, random replicas will be selected.

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

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.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

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.

citations
boolean (Citations)
Default: false

Whether to include the citations for the answer in the response

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

Security metadata for the request. If not provided, the search request is done without the security lookup phase.

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. field_extension will add the text of the matching resource's specified fields to the context. If empty, the default strategy is used.

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. If empty, the default strategy is used with the image of the paragraph.

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.

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 the query to improve search)
Default: false

Consume LLM tokens to rephrase the query so the semantic search is better

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 of the desired 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.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fields": [ ],
  • "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": [ ],
  • "shards": [ ],
  • "context": [
    ],
  • "extra_context": [
    ],
  • "autofilter": false,
  • "highlight": false,
  • "resource_filters": [ ],
  • "prompt": "string",
  • "citations": false,
  • "security": {
    },
  • "rag_strategies": [ ],
  • "rag_images_strategies": [ ],
  • "debug": false,
  • "generative_model": "string",
  • "max_tokens": 0,
  • "rephrase": false,
  • "prefer_markdown": false,
  • "answer_json_schema": {
    }
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "status": "string",
  • "retrieval_results": {
    },
  • "learning_id": "",
  • "relations": {
    },
  • "citations": { },
  • "prompt_context": [
    ],
  • "metadata": {
    },
  • "error_details": "string"
}

List resources of a Knowledge Box

List resources of a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
query Parameters
query
string (Query)
Default: ""

The query to search for

filters
Array of strings (Filters)
Default: ""

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

faceted
Array of strings (Faceted) <= 50 items
Default: ""

The list of facets to calculate. The facets follow the same syntax as filters: https://docs.nuclia.dev/docs/docs/using/search/#filters

sort_field
string (Sort field)
Enum: "score" "created" "modified" "title"

Field to sort results with

Sort limit (integer) or Sort limit (null) (Sort limit)
sort_order
string (Sort order)
Default: "desc"
Enum: "asc" "desc"

Order to sort results with

page_number
integer (Page number)
Default: 0

The page number of the results to return

page_size
integer (Page size) <= 200
Default: 20

The number of results to return per page. The maximum number of results per page allowed is 200.

shards
Array of strings (Shards)
Default: ""

The list of shard replicas to search in. If empty, random replicas will be selected.

ResourceProcessingStatus (string) or With processing status (null) (With processing status)

Filter results by resource processing status

debug
boolean (Debug mode)
Default: false

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

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.

Responses

Response samples

Content type
application/json
{
  • "resources": { },
  • "sentences": {
    },
  • "paragraphs": {
    },
  • "fulltext": {
    },
  • "relations": {
    },
  • "nodes": [
    ],
  • "shards": [
    ],
  • "autofilters": [ ]
}

List resources of a Knowledge Box

List resources of a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
Request Body schema: application/json
required
query
string (Query)
Default: ""

The query to search for

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

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

faceted
Array of strings (Faceted) <= 50 items
Default: []

The list of facets to calculate. The facets follow the same syntax as filters: https://docs.nuclia.dev/docs/docs/using/search/#filters

SortOptions (object) or Sort options (null) (Sort options)

Options for results sorting

page_number
integer (Page number)
Default: 0

The page number of the results to return

page_size
integer (Page size) <= 200
Default: 20

The number of results to return per page. The maximum number of results per page allowed is 200.

shards
Array of strings (Shards)
Default: []

The list of shard replicas to search in. If empty, random replicas will be selected.

debug
boolean (Debug mode)
Default: false

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

ResourceProcessingStatus (string) or With processing status (null) (With processing status)

Filter results by resource processing status

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.

Responses

Request samples

Content type
application/json
{
  • "query": "",
  • "filters": [ ],
  • "faceted": [ ],
  • "sort": {
    },
  • "page_number": 0,
  • "page_size": 20,
  • "shards": [ ],
  • "debug": false,
  • "with_status": "PENDING",
  • "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"
}

Response samples

Content type
application/json
{
  • "resources": { },
  • "sentences": {
    },
  • "paragraphs": {
    },
  • "fulltext": {
    },
  • "relations": {
    },
  • "nodes": [
    ],
  • "shards": [
    ],
  • "autofilters": [ ]
}

Chat on a Knowledge Box Deprecated

Chat on a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
header Parameters
x-ndb-client
string (X-Ndb-Client)
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
query
required
string (Query)

The query to get a generative answer for

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/docs/using/search/#search-in-a-specific-field

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

The list of filters to apply. Filtering examples can be found here: https://docs.nuclia.dev/docs/docs/using/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: ["vectors","paragraphs","relations"]
Items Enum: "vectors" "paragraphs" "relations"

Features enabled for the chat endpoint. Semantic search is done if vectors is included. If paragraphs 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.

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"]
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

shards
Array of strings (Shards)
Default: []

The list of shard replicas to search in. If empty, random replicas will be selected.

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

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.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

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.

citations
boolean (Citations)
Default: false

Whether to include the citations for the answer in the response

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

Security metadata for the request. If not provided, the search request is done without the security lookup phase.

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. field_extension will add the text of the matching resource's specified fields to the context. If empty, the default strategy is used.

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. If empty, the default strategy is used with the image of the paragraph.

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.

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 the query to improve search)
Default: false

Consume LLM tokens to rephrase the query so the semantic search is better

prefer_markdown
boolean (Prefer markdown)
Default: false

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

Responses

Request samples

Content type
application/json
Example

You can ask a question to your knowledge box

{
  • "query": "Who won the league final?"
}

Response samples

Content type
application/json
null

Send Feedback

Send feedback for a search operation in a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
header Parameters
x-ndb-client
string (X-Ndb-Client)
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:
Request Body schema: application/json
required
ident
required
string (Request identifier)

Id of the request to provide feedback for. This id is returned in the response header Nuclia-Learning-Id of the chat endpoint.

good
required
boolean (Good)

Whether the result was good or not

task
required
string (Task)
Value: "CHAT"

The task the feedback is for. For now, only CHAT task is available

Value: "CHAT"
Feedback (string) or Feedback (null) (Feedback)

Feedback text

Responses

Request samples

Content type
application/json
{
  • "ident": "string",
  • "good": true,
  • "task": "CHAT",
  • "feedback": "string"
}

Response samples

Content type
application/json
null

Find Knowledge Box

Find on a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
query Parameters
query
string (Query)
Default: ""

The query to search for

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/docs/using/search/#search-in-a-specific-field

filters
Array of strings (Filters)
Default: ""

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

page_number
integer (Page number)
Default: 0

The page number of the results to return

page_size
integer (Page size) <= 200
Default: 20

The number of results to return per page. The maximum number of results per page allowed is 200.

Min Score (number) or Min Score (null) (Min Score)
Deprecated

Minimum similarity score to filter vector index results. If not specified, the default minimum score of the semantic model associated to the Knowledge Box will be used. Check out the documentation for more information on how to use this parameter: https://docs.nuclia.dev/docs/docs/using/search/#minimum-score

Min Score Semantic (number) or Min Score Semantic (null) (Min Score Semantic)

Minimum semantic similarity score to filter vector index results. If not specified, the default minimum score of the semantic model associated to the Knowledge Box will be used. Check out the documentation for more information on how to use this parameter: https://docs.nuclia.dev/docs/docs/using/search/#minimum-score

min_score_bm25
number (Min Score Bm25) >= 0
Default: 0

Minimum bm25 score to filter paragraph and document index results

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

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

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.

features
Array of strings (Search features)
Default: "paragraph&features=vector"
Items Enum: "paragraph" "document" "relations" "vector"

List of search features to use. Each value corresponds to a lookup into on of the different indexes.

debug
boolean (Debug mode)
Default: false

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

highlight
boolean (Highlight)
Default: false

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

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
Array of strings (Field type filter)
Default: "text&field_type=file&field_type=link&field_type=conversation&field_type=generic"
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

with_duplicates
boolean (With duplicate paragraphs)
Default: false

Whether to return duplicate paragraphs on the same document

with_synonyms
boolean (With custom synonyms)
Default: false

Whether to return matches for custom knowledge box synonyms of the query terms. Note: only supported for paragraph and document search options.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

security_groups
Array of strings (Security groups)
Default: ""

List of security groups to filter search results for. Only resources matching the query and containing the specified security groups will be returned. If empty, all resources will be considered for the search.

header Parameters
x-ndb-client
string (X-Ndb-Client)
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
{
  • "resources": {
    },
  • "relations": {
    },
  • "query": "string",
  • "total": 0,
  • "page_number": 0,
  • "page_size": 20,
  • "next_page": false,
  • "nodes": [
    ],
  • "shards": [
    ],
  • "autofilters": [ ],
  • "min_score": {
    },
  • "best_matches": [ ]
}

Find Knowledge Box

Find on a Knowledge Box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
header Parameters
x-ndb-client
string (X-Ndb-Client)
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:
Request Body schema: application/json
required
query
string (Query)
Default: ""

The query to search for

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/docs/using/search/#search-in-a-specific-field

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

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

page_number
integer (Page number)
Default: 0

The page number of the results to return

page_size
integer (Page size) <= 200
Default: 20

The number of results to return per page. The maximum number of results per page allowed is 200.

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.

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.

features
Array of strings (Search features)
Default: ["paragraph","vector"]
Items Enum: "paragraph" "document" "relations" "vector"

List of search features to use. Each value corresponds to a lookup into on of the different indexes.

debug
boolean (Debug mode)
Default: false

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

highlight
boolean (Highlight)
Default: false

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

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"]
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

shards
Array of strings (Shards)
Default: []

The list of shard replicas to search in. If empty, random replicas will be selected.

Array of Search Vector (numbers) or Search Vector (null) (Search Vector)

The vector to perform the search with. If not provided, NucliaDB will use Nuclia Predict API to create the vector off from the query.

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

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

with_duplicates
boolean (With duplicate paragraphs)
Default: false

Whether to return duplicate paragraphs on the same document

with_synonyms
boolean (With custom synonyms)
Default: false

Whether to return matches for custom knowledge box synonyms of the query terms. Note: only supported for paragraph and document search options.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

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.

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

Security metadata for the request. If not provided, the search request is done without the security lookup phase.

rephrase
boolean (Rephrase the query to improve search)
Default: false

Consume LLM tokens to rephrase the query so the semantic search is better

Responses

Request samples

Content type
application/json

Perform a hybrid search that will return text and semantic results matching the query

{
  • "query": "How can I be an effective product manager?",
  • "features": [
    ]
}

Response samples

Content type
application/json
{
  • "resources": {
    },
  • "relations": {
    },
  • "query": "string",
  • "total": 0,
  • "page_number": 0,
  • "page_size": 20,
  • "next_page": false,
  • "nodes": [
    ],
  • "shards": [
    ],
  • "autofilters": [ ],
  • "min_score": {
    },
  • "best_matches": [ ]
}

Predict API Proxy

Convenience endpoint that proxies requests to the Predict API. It adds the Knowledge Box configuration settings as headers to the predict API request. Refer to the Predict API documentation for more details about the request and response models: https://docs.nuclia.dev/docs/nua-api#tag/Predict

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
endpoint
required
string (PredictProxiedEndpoints)
Enum: "tokens" "chat" "rephrase"

Enum for the different endpoints that are proxied to the Predict API

Responses

Response samples

Content type
application/json
null

Predict API Proxy

Convenience endpoint that proxies requests to the Predict API. It adds the Knowledge Box configuration settings as headers to the predict API request. Refer to the Predict API documentation for more details about the request and response models: https://docs.nuclia.dev/docs/nua-api#tag/Predict

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
endpoint
required
string (PredictProxiedEndpoints)
Enum: "tokens" "chat" "rephrase"

Enum for the different endpoints that are proxied to the Predict API

Responses

Response samples

Content type
application/json
null

Ask a resource (by id)

Ask questions to a resource

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
header Parameters
x-ndb-client
string (X-Ndb-Client)
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
query
required
string (Query)

The query to get a generative answer for

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/docs/using/search/#search-in-a-specific-field

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

The list of filters to apply. Filtering examples can be found here: https://docs.nuclia.dev/docs/docs/using/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: ["vectors","paragraphs","relations"]
Items Enum: "vectors" "paragraphs" "relations"

Features enabled for the chat endpoint. Semantic search is done if vectors is included. If paragraphs 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.

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"]
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

shards
Array of strings (Shards)
Default: []

The list of shard replicas to search in. If empty, random replicas will be selected.

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

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.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

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.

citations
boolean (Citations)
Default: false

Whether to include the citations for the answer in the response

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

Security metadata for the request. If not provided, the search request is done without the security lookup phase.

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. field_extension will add the text of the matching resource's specified fields to the context. If empty, the default strategy is used.

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. If empty, the default strategy is used with the image of the paragraph.

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.

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 the query to improve search)
Default: false

Consume LLM tokens to rephrase the query so the semantic search is better

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 of the desired 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.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fields": [ ],
  • "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": [ ],
  • "shards": [ ],
  • "context": [
    ],
  • "extra_context": [
    ],
  • "autofilter": false,
  • "highlight": false,
  • "resource_filters": [ ],
  • "prompt": "string",
  • "citations": false,
  • "security": {
    },
  • "rag_strategies": [ ],
  • "rag_images_strategies": [ ],
  • "debug": false,
  • "generative_model": "string",
  • "max_tokens": 0,
  • "rephrase": false,
  • "prefer_markdown": false,
  • "answer_json_schema": {
    }
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "status": "string",
  • "retrieval_results": {
    },
  • "learning_id": "",
  • "relations": {
    },
  • "citations": { },
  • "prompt_context": [
    ],
  • "metadata": {
    },
  • "error_details": "string"
}

Chat with a resource (by id) Deprecated

Chat with a resource

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
header Parameters
x-ndb-client
string (X-Ndb-Client)
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
query
required
string (Query)

The query to get a generative answer for

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/docs/using/search/#search-in-a-specific-field

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

The list of filters to apply. Filtering examples can be found here: https://docs.nuclia.dev/docs/docs/using/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: ["vectors","paragraphs","relations"]
Items Enum: "vectors" "paragraphs" "relations"

Features enabled for the chat endpoint. Semantic search is done if vectors is included. If paragraphs 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.

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"]
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

shards
Array of strings (Shards)
Default: []

The list of shard replicas to search in. If empty, random replicas will be selected.

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

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.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

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.

citations
boolean (Citations)
Default: false

Whether to include the citations for the answer in the response

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

Security metadata for the request. If not provided, the search request is done without the security lookup phase.

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. field_extension will add the text of the matching resource's specified fields to the context. If empty, the default strategy is used.

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. If empty, the default strategy is used with the image of the paragraph.

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.

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 the query to improve search)
Default: false

Consume LLM tokens to rephrase the query so the semantic search is better

prefer_markdown
boolean (Prefer markdown)
Default: false

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

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fields": [ ],
  • "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": [ ],
  • "shards": [ ],
  • "context": [
    ],
  • "extra_context": [
    ],
  • "autofilter": false,
  • "highlight": false,
  • "resource_filters": [ ],
  • "prompt": "string",
  • "citations": false,
  • "security": {
    },
  • "rag_strategies": [ ],
  • "rag_images_strategies": [ ],
  • "debug": false,
  • "generative_model": "string",
  • "max_tokens": 0,
  • "rephrase": false,
  • "prefer_markdown": false
}

Response samples

Content type
application/json
null

Search on Resource

Search on a single resource

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
rid
required
string (Rid)
query Parameters
query
required
string (Query)
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/docs/using/search/#search-in-a-specific-field

filters
Array of strings (Filters)
Default: ""

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

faceted
Array of strings (Faceted) <= 50 items
Default: ""

The list of facets to calculate. The facets follow the same syntax as filters: https://docs.nuclia.dev/docs/docs/using/search/#filters

SortField (string) or Sort field (null) (Sort field)

Field to sort results with

sort_order
string (Sort order)
Default: "desc"
Enum: "asc" "desc"

Order to sort results with

page_number
integer (Page number)
Default: 0

The page number of the results to return

page_size
integer (Page size) <= 200
Default: 20

The number of results to return per page. The maximum number of results per page allowed is 200.

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.

highlight
boolean (Highlight)
Default: false

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

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

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

field_type
Array of strings (Field type filter)
Default: "text&field_type=file&field_type=link&field_type=conversation&field_type=generic"
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

debug
boolean (Debug mode)
Default: false

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

shards
Array of strings (Shards)
Default: ""

The list of shard replicas to search in. If empty, random replicas will be selected.

header Parameters
x-ndb-client
string (X-Ndb-Client)
Default: api
Enum: "api" "widget" "web" "dashboard" "desktop" "chrome_extension"

Responses

Response samples

Content type
application/json
{
  • "sentences": {
    },
  • "paragraphs": {
    },
  • "relations": {
    },
  • "nodes": [
    ],
  • "shards": [
    ]
}

Search Knowledge Box

Search on a Knowledge Box and retrieve separate results for documents, paragraphs, and sentences. Usually, it is better to use find

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
query Parameters
query
string (Query)
Default: ""

The query to search for

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/docs/using/search/#search-in-a-specific-field

filters
Array of strings (Filters)
Default: ""

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

faceted
Array of strings (Faceted) <= 50 items
Default: ""

The list of facets to calculate. The facets follow the same syntax as filters: https://docs.nuclia.dev/docs/docs/using/search/#filters

sort_field
string (Sort field)
Enum: "score" "created" "modified" "title"

Field to sort results with

Sort limit (integer) or Sort limit (null) (Sort limit)
sort_order
string (Sort order)
Default: "desc"
Enum: "asc" "desc"

Order to sort results with

page_number
integer (Page number)
Default: 0

The page number of the results to return

page_size
integer (Page size) <= 200
Default: 20

The number of results to return per page. The maximum number of results per page allowed is 200.

Min Score (number) or Min Score (null) (Min Score)
Deprecated

Minimum similarity score to filter vector index results. If not specified, the default minimum score of the semantic model associated to the Knowledge Box will be used. Check out the documentation for more information on how to use this parameter: https://docs.nuclia.dev/docs/docs/using/search/#minimum-score

Min Score Semantic (number) or Min Score Semantic (null) (Min Score Semantic)

Minimum semantic similarity score to filter vector index results. If not specified, the default minimum score of the semantic model associated to the Knowledge Box will be used. Check out the documentation for more information on how to use this parameter: https://docs.nuclia.dev/docs/docs/using/search/#minimum-score

min_score_bm25
number (Min Score Bm25) >= 0
Default: 0

Minimum bm25 score to filter paragraph and document index results

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

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

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.

features
Array of strings (Search features)
Default: "paragraph&features=document&features=vector"
Items Enum: "paragraph" "document" "relations" "vector"

List of search features to use. Each value corresponds to a lookup into on of the different indexes.

debug
boolean (Debug mode)
Default: false

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

highlight
boolean (Highlight)
Default: false

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

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
Array of strings (Field type filter)
Default: "text&field_type=file&field_type=link&field_type=conversation&field_type=generic"
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

shards
Array of strings (Shards)
Default: ""

The list of shard replicas to search in. If empty, random replicas will be selected.

with_duplicates
boolean (With duplicate paragraphs)
Default: false

Whether to return duplicate paragraphs on the same document

with_synonyms
boolean (With custom synonyms)
Default: false

Whether to return matches for custom knowledge box synonyms of the query terms. Note: only supported for paragraph and document search options.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

security_groups
Array of strings (Security groups)
Default: ""

List of security groups to filter search results for. Only resources matching the query and containing the specified security groups will be returned. If empty, all resources will be considered for the search.

header Parameters
x-ndb-client
string (X-Ndb-Client)
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
{
  • "resources": { },
  • "sentences": {
    },
  • "paragraphs": {
    },
  • "fulltext": {
    },
  • "relations": {
    },
  • "nodes": [
    ],
  • "shards": [
    ],
  • "autofilters": [ ]
}

Search Knowledge Box

Search on a Knowledge Box and retrieve separate results for documents, paragraphs, and sentences. Usually, it is better to use find

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
header Parameters
x-ndb-client
string (X-Ndb-Client)
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:
Request Body schema: application/json
required
query
string (Query)
Default: ""

The query to search for

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/docs/using/search/#search-in-a-specific-field

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

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

page_number
integer (Page number)
Default: 0

The page number of the results to return

page_size
integer (Page size) <= 200
Default: 20

The number of results to return per page. The maximum number of results per page allowed is 200.

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.

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.

features
Array of strings (Search features)
Default: ["paragraph","document","vector"]
Items Enum: "paragraph" "document" "relations" "vector"

List of search features to use. Each value corresponds to a lookup into on of the different indexes.

debug
boolean (Debug mode)
Default: false

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

highlight
boolean (Highlight)
Default: false

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

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"]
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

shards
Array of strings (Shards)
Default: []

The list of shard replicas to search in. If empty, random replicas will be selected.

Array of Search Vector (numbers) or Search Vector (null) (Search Vector)

The vector to perform the search with. If not provided, NucliaDB will use Nuclia Predict API to create the vector off from the query.

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

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

with_duplicates
boolean (With duplicate paragraphs)
Default: false

Whether to return duplicate paragraphs on the same document

with_synonyms
boolean (With custom synonyms)
Default: false

Whether to return matches for custom knowledge box synonyms of the query terms. Note: only supported for paragraph and document search options.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

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.

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

Security metadata for the request. If not provided, the search request is done without the security lookup phase.

rephrase
boolean (Rephrase the query to improve search)
Default: false

Consume LLM tokens to rephrase the query so the semantic search is better

faceted
Array of strings (Faceted) <= 50 items
Default: []

The list of facets to calculate. The facets follow the same syntax as filters: https://docs.nuclia.dev/docs/docs/using/search/#filters

SortOptions (object) or Sort options (null) (Sort options)

Options for results sorting

Responses

Request samples

Content type
application/json
Example

For a complete list of filters, visit: https://github.com/nuclia/nucliadb/blob/main/docs/internal/SEARCH.md#filters-and-facets

{
  • "query": "Noam Chomsky",
  • "filters": [
    ],
  • "features": [
    ]
}

Response samples

Content type
application/json
{
  • "resources": { },
  • "sentences": {
    },
  • "paragraphs": {
    },
  • "fulltext": {
    },
  • "relations": {
    },
  • "nodes": [
    ],
  • "shards": [
    ],
  • "autofilters": [ ]
}

Ask a resource (by slug)

Ask questions to a resource

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
slug
required
string (Slug)
header Parameters
x-ndb-client
string (X-Ndb-Client)
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
query
required
string (Query)

The query to get a generative answer for

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/docs/using/search/#search-in-a-specific-field

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

The list of filters to apply. Filtering examples can be found here: https://docs.nuclia.dev/docs/docs/using/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: ["vectors","paragraphs","relations"]
Items Enum: "vectors" "paragraphs" "relations"

Features enabled for the chat endpoint. Semantic search is done if vectors is included. If paragraphs 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.

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"]
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

shards
Array of strings (Shards)
Default: []

The list of shard replicas to search in. If empty, random replicas will be selected.

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

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.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

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.

citations
boolean (Citations)
Default: false

Whether to include the citations for the answer in the response

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

Security metadata for the request. If not provided, the search request is done without the security lookup phase.

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. field_extension will add the text of the matching resource's specified fields to the context. If empty, the default strategy is used.

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. If empty, the default strategy is used with the image of the paragraph.

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.

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 the query to improve search)
Default: false

Consume LLM tokens to rephrase the query so the semantic search is better

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 of the desired 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.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fields": [ ],
  • "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": [ ],
  • "shards": [ ],
  • "context": [
    ],
  • "extra_context": [
    ],
  • "autofilter": false,
  • "highlight": false,
  • "resource_filters": [ ],
  • "prompt": "string",
  • "citations": false,
  • "security": {
    },
  • "rag_strategies": [ ],
  • "rag_images_strategies": [ ],
  • "debug": false,
  • "generative_model": "string",
  • "max_tokens": 0,
  • "rephrase": false,
  • "prefer_markdown": false,
  • "answer_json_schema": {
    }
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "status": "string",
  • "retrieval_results": {
    },
  • "learning_id": "",
  • "relations": {
    },
  • "citations": { },
  • "prompt_context": [
    ],
  • "metadata": {
    },
  • "error_details": "string"
}

Chat with a resource (by slug) Deprecated

Chat with a resource

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
slug
required
string (Slug)
header Parameters
x-ndb-client
string (X-Ndb-Client)
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
query
required
string (Query)

The query to get a generative answer for

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/docs/using/search/#search-in-a-specific-field

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

The list of filters to apply. Filtering examples can be found here: https://docs.nuclia.dev/docs/docs/using/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: ["vectors","paragraphs","relations"]
Items Enum: "vectors" "paragraphs" "relations"

Features enabled for the chat endpoint. Semantic search is done if vectors is included. If paragraphs 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.

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"]
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

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

Controls which parts of the extracted metadata are serialized on search results

shards
Array of strings (Shards)
Default: []

The list of shard replicas to search in. If empty, random replicas will be selected.

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

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.

autofilter
boolean (Automatic search filtering)
Default: false

If set to true, the search will automatically add filters to the query. For example, it will filter results containing the entities detected in the query

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.

citations
boolean (Citations)
Default: false

Whether to include the citations for the answer in the response

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

Security metadata for the request. If not provided, the search request is done without the security lookup phase.

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. field_extension will add the text of the matching resource's specified fields to the context. If empty, the default strategy is used.

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. If empty, the default strategy is used with the image of the paragraph.

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.

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 the query to improve search)
Default: false

Consume LLM tokens to rephrase the query so the semantic search is better

prefer_markdown
boolean (Prefer markdown)
Default: false

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

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fields": [ ],
  • "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": [ ],
  • "shards": [ ],
  • "context": [
    ],
  • "extra_context": [
    ],
  • "autofilter": false,
  • "highlight": false,
  • "resource_filters": [ ],
  • "prompt": "string",
  • "citations": false,
  • "security": {
    },
  • "rag_strategies": [ ],
  • "rag_images_strategies": [ ],
  • "debug": false,
  • "generative_model": "string",
  • "max_tokens": 0,
  • "rephrase": false,
  • "prefer_markdown": false
}

Response samples

Content type
application/json
null

Suggest on a knowledge box

Suggestions on a knowledge box

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
query Parameters
query
required
string (Query)

The query to get suggestions for

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/docs/using/search/#search-in-a-specific-field

filters
Array of strings (Filters)
Default: ""

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

faceted
Array of strings (Faceted) <= 50 items
Default: ""

The list of facets to calculate. The facets follow the same syntax as filters: https://docs.nuclia.dev/docs/docs/using/search/#filters

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.

features
Array of strings (Suggest features)
Default: "paragraph&features=entities"
Items Enum: "paragraph" "entities"

Features enabled for the suggest endpoint.

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
Array of strings (Field type filter)
Default: "text&field_type=file&field_type=link&field_type=conversation&field_type=generic"
Items Enum: "text" "file" "link" "conversation" "generic"

Filter search results to match paragraphs of a specific field type. E.g: ['conversation', 'text']

debug
boolean (Debug mode)
Default: false

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

highlight
boolean (Highlight)
Default: false

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

header Parameters
x-ndb-client
string (X-Ndb-Client)
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
{
  • "paragraphs": {
    },
  • "entities": {
    },
  • "shards": [
    ]
}

Summarize your documents

Summarize Your Documents

Authorization roles

Authenticated user needs to fulfill one of this roles, otherwise the request will be rejected with a 403 response.

  • READER
path Parameters
kbid
required
string (Kbid)
Request Body schema: application/json
required
Generative model (string) or Generative model (null) (Generative model)

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

User prompt (string) or User prompt (null) (User prompt)

Optional custom prompt input by the user

resources
required
Array of strings (Resources) [ 1 .. 100 ] items

Uids or slugs of the resources to summarize. If the resources are not found, they will be ignored.

summary_kind
string (Summary kind)
Default: "simple"
Enum: "simple" "extended"

Option to customize how the summary will be

Responses

Request samples

Content type
application/json
{
  • "generative_model": "string",
  • "user_prompt": "string",
  • "resources": [
    ],
  • "summary_kind": "simple"
}

Response samples

Content type
application/json
{
  • "resources": { },
  • "summary": ""
}