Skip to main content

import Badge from '@site/src/components/Badge';

Push content to your Knowledge Box

A Knowledge Box is a collection of content. When Nuclia runs a search, it does so over a given Knowledge Box. In most cases, you will just need one unique Knowledge Box for your application.

When creating your account, Nuclia automatically creates a default Knowledge Box for you.

Push files using the Nuclia Dashboard

In the Nuclia Dashboard, go to the left navigation bar and click on Add file in the Contents section and select the files you want to push.

Indexing files might take a while, depending on the size and nature of the file. We recommend starting with a few small files so you can start playing with Nuclia right away.

You can also upload some links and the corresponding web pages will be indexed.

Push content using the API


What kind of content can be stored in a Knowledge Box?

In the previous example, you created a resource containing a single file. But a resource can contain other kinds of content. These contents are stored in fields of different types:

  • file
  • text
  • link
  • conversation
  • keywords
  • datetime

Imagine you want to store employee information as a resource: their CV could be a file, their city a keyword field, their birth date a datetime field, their linkedin and twitter profiles would be link fields, notes from the company a text field, and the conversation you had with them a conversation field.

You can freely define these content fields, and give them the id you want. Each resource also has generic fields which are predefined attributes (like title, summary, labels, tags, etc.) which correspond to the Nuclia schema.

Get an API key

In the Nuclia Dashboard, go to the left navigation bar and click on API Keys.

Enter a title for the new API key, select the Contributor role and click on Add.

The new API key appears in the list and a dialog pops up allowing you to copy the generated API key.

Copy the resulting API key as it won’t be visible again after closing the dialog.

Call the API


Your Knowledge Box API endpoint is displayed on the Nuclia Dashboard home page.

The full API documentation is available here.

And here is a Postman collection providing typical use of the API.

Push a file

Now you can push files to your Knowledge Box using the Nuclia API:

curl https://<zone><your-knowledge-box-id>/upload \
-H "X-NUCLIA-SERVICEACCOUNT: Bearer <your-api-key>" \
-T /path/to/file

It will automatically create a new resource in your Knowledge Box and store the file there.

Resources are entries in your Nuclia Knowledge Box. A resource can contain any kind of content: a text, a video, a picture, etc. It can contain multiple files and also contains metadata: some being defined by you, some automatically built by Nuclia.


When using the /upload endpoint to create a resource, you can only pass the file content. If you also need to set a title, some labels, or any other kind of metadata, you will need to first create the resource with a POST /resources request with the x-synchronous header set to true, then add the file as a file field upload.

This example shows how to import files with a title and a label.

Push a text

Instead of uploading a file, you can also create a resource manually and provide its text content:

curl https://<zone><your-knowledge-box-id>/resources \
-H "X-NUCLIA-SERVICEACCOUNT: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{"title":"Little Prince","texts":{"chapter-1":{"format":"PLAIN","body":"Draw me a sheep"}}}'

You can also create a resource from a link:

curl https://<zone><your-knowledge-box-id>/resources \
-H "X-NUCLIA-SERVICEACCOUNT: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{"title":"Antoine de Saint-Exupéry","links":{"wikipedia":{"uri":""}}}'

The corresponding web page content will be indexed (be aware that Nuclia does not act as a web crawler. It will identify all the links in the page and store them as entities in the resource, but it will not index their content).

Push a cloud-based file

If you need to index a file stored on a cloud service, you can send it directly to Nuclia the same way you sent a web page in the previous example, using the files entry instead of links:

curl https://<zone><your-knowledge-box-id>/resources \
-H "X-NUCLIA-SERVICEACCOUNT: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{"title":"Dev team weekly meeting","files":{"weekly-meeting":{"file": {"uri":"https://somecloud/path/to/meeting.mp4", "content_type": "video/mp4"}}}}'

If the file is not publicly accessible, the file entry accepts an extra_headers attribute allowing it to pass an API key or any other type of credential.