Hybrid search combining semantic, keyword, fulltext and graph search, the find endpoint optimized for RAG context retrieval, plus suggest autocomplete over a Knowledge Box.
openapi: 3.0.1
info:
title: Nuclia RAG-as-a-Service API
description: >-
Specification of the Nuclia (Progress Agentic RAG) cloud API. Nuclia turns
unstructured data - documents, files, audio, video, web pages and
conversations - into searchable, queryable Knowledge Boxes. This document
covers the regional NucliaDB REST API (Knowledge Boxes, resources and
ingestion, search, find, ask/chat RAG answers) and the Nuclia Understanding
API (NUA / Predict) endpoints. All endpoints are served from a regional
zone host.
termsOfService: https://nuclia.com/terms-and-conditions/
contact:
name: Nuclia Support
url: https://nuclia.com
version: '1.0'
servers:
- url: https://{zone}.nuclia.cloud/api
description: >-
Regional Nuclia cloud zone host. Replace {zone} with your account region
(for example europe-1 or aws-us-east-2-1). Following the Progress rebrand
the same surface is also served from https://{region}.rag.progress.cloud/api.
variables:
zone:
default: europe-1
description: The Nuclia regional zone for your account.
paths:
/v1/kb/{kbid}:
get:
operationId: getKnowledgeBox
tags:
- Knowledge Boxes
summary: Get a Knowledge Box
description: Retrieve configuration and metadata for a Knowledge Box.
parameters:
- $ref: '#/components/parameters/Kbid'
responses:
'200':
description: Knowledge Box configuration
content:
application/json:
schema:
$ref: '#/components/schemas/KnowledgeBox'
'403':
$ref: '#/components/responses/Forbidden'
/v1/kb/{kbid}/counters:
get:
operationId: getKnowledgeBoxCounters
tags:
- Knowledge Boxes
summary: Get Knowledge Box counters
description: Return resource, paragraph, field and sentence counts for a Knowledge Box.
parameters:
- $ref: '#/components/parameters/Kbid'
responses:
'200':
description: Knowledge Box counters
content:
application/json:
schema:
$ref: '#/components/schemas/Counters'
/v1/kb/{kbid}/labelsets:
get:
operationId: getLabelSets
tags:
- Knowledge Boxes
summary: Get label sets
description: Return all label sets configured on the Knowledge Box.
parameters:
- $ref: '#/components/parameters/Kbid'
responses:
'200':
description: Label sets
content:
application/json:
schema:
type: object
/v1/kb/{kbid}/labelset/{labelset}:
put:
operationId: setLabelSet
tags:
- Knowledge Boxes
summary: Set a label set
description: Create or update a label set used to classify resources.
parameters:
- $ref: '#/components/parameters/Kbid'
- name: labelset
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LabelSet'
responses:
'200':
description: Label set stored
'403':
$ref: '#/components/responses/Forbidden'
/v1/kb/{kbid}/resource:
post:
operationId: createResource
tags:
- Resources
summary: Create a resource
description: >-
Create a new resource in a Knowledge Box. Text, link, file and
conversation fields may be supplied inline; uploaded binaries are
processed asynchronously and indexed for search.
parameters:
- $ref: '#/components/parameters/Kbid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResourcePayload'
responses:
'201':
description: Resource created
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceCreated'
'403':
$ref: '#/components/responses/Forbidden'
/v1/kb/{kbid}/resources:
get:
operationId: listResources
tags:
- Resources
summary: List resources
description: List resources in a Knowledge Box with pagination.
parameters:
- $ref: '#/components/parameters/Kbid'
- name: page
in: query
schema:
type: integer
default: 0
- name: size
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Paginated resource list
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceList'
/v1/kb/{kbid}/resource/{rid}:
get:
operationId: getResource
tags:
- Resources
summary: Get a resource
description: Retrieve a resource by its id, optionally including extracted data.
parameters:
- $ref: '#/components/parameters/Kbid'
- $ref: '#/components/parameters/Rid'
- name: show
in: query
description: Parts of the resource to return (basic, values, extracted, errors).
schema:
type: array
items:
type: string
responses:
'200':
description: Resource
content:
application/json:
schema:
$ref: '#/components/schemas/Resource'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: modifyResource
tags:
- Resources
summary: Modify a resource
description: Update fields, metadata or labels of an existing resource.
parameters:
- $ref: '#/components/parameters/Kbid'
- $ref: '#/components/parameters/Rid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResourcePayload'
responses:
'200':
description: Resource modified
'403':
$ref: '#/components/responses/Forbidden'
delete:
operationId: deleteResource
tags:
- Resources
summary: Delete a resource
description: Delete a resource and its indexed data from the Knowledge Box.
parameters:
- $ref: '#/components/parameters/Kbid'
- $ref: '#/components/parameters/Rid'
responses:
'204':
description: Resource deleted
'403':
$ref: '#/components/responses/Forbidden'
/v1/kb/{kbid}/resource/{rid}/file/{field}:
put:
operationId: uploadFileField
tags:
- Resources
summary: Upload a file field
description: >-
Upload a binary file into a file field of a resource. The file is sent
through Nuclia's processing pipeline (extraction, embedding, indexing).
Large files should use the TUS resumable upload endpoint.
parameters:
- $ref: '#/components/parameters/Kbid'
- $ref: '#/components/parameters/Rid'
- name: field
in: path
required: true
schema:
type: string
- name: X-Filename
in: header
schema:
type: string
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'201':
description: File field stored and queued for processing
'403':
$ref: '#/components/responses/Forbidden'
/v1/kb/{kbid}/upload:
post:
operationId: uploadToKnowledgeBox
tags:
- Resources
summary: Upload a binary directly to a Knowledge Box
description: >-
Upload a binary file directly to a Knowledge Box. Nuclia creates a
resource automatically and runs the file through the processing
pipeline for extraction, embedding and indexing.
parameters:
- $ref: '#/components/parameters/Kbid'
- name: X-Filename
in: header
schema:
type: string
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'201':
description: Resource created from upload
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceCreated'
/v1/kb/{kbid}/search:
post:
operationId: search
tags:
- Search
summary: Search a Knowledge Box
description: >-
Run a hybrid search (semantic + keyword + fulltext) across a Knowledge
Box and return matching resources, paragraphs and sentences.
parameters:
- $ref: '#/components/parameters/Kbid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Search results
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResults'
/v1/kb/{kbid}/find:
post:
operationId: find
tags:
- Search
summary: Find in a Knowledge Box
description: >-
Run a find query - the search variant optimized for RAG context
retrieval - returning results grouped and scored by resource and
paragraph, including optional graph search.
parameters:
- $ref: '#/components/parameters/Kbid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Find results
content:
application/json:
schema:
$ref: '#/components/schemas/FindResults'
/v1/kb/{kbid}/suggest:
get:
operationId: suggest
tags:
- Search
summary: Suggest on a Knowledge Box
description: Return autocomplete suggestions and entity matches for a partial query.
parameters:
- $ref: '#/components/parameters/Kbid'
- name: query
in: query
required: true
schema:
type: string
responses:
'200':
description: Suggestions
content:
application/json:
schema:
type: object
/v1/kb/{kbid}/ask:
post:
operationId: ask
tags:
- Ask
summary: Ask a Knowledge Box (RAG generative answer)
description: >-
Ask a natural-language question against a Knowledge Box. Nuclia retrieves
the most relevant context (semantic, keyword and graph search), builds a
prompt and returns a generative answer with the supporting resources as
citations. When the request sets `Accept: application/x-ndjson` (or the
SDK streaming flag), the answer is streamed back as newline-delimited
JSON / Server-Sent events.
parameters:
- $ref: '#/components/parameters/Kbid'
- name: X-Synchronous
in: header
description: Set to true to receive a single buffered JSON answer instead of a stream.
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AskRequest'
responses:
'200':
description: >-
Generative answer. Streamed as application/x-ndjson by default, or a
single AskResponse object when X-Synchronous is true.
content:
application/json:
schema:
$ref: '#/components/schemas/AskResponse'
application/x-ndjson:
schema:
$ref: '#/components/schemas/AskResponse'
/v1/kb/{kbid}/summarize:
post:
operationId: summarize
tags:
- Ask
summary: Summarize resources
description: Generate a summary across one or more resources in the Knowledge Box.
parameters:
- $ref: '#/components/parameters/Kbid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SummarizeRequest'
responses:
'200':
description: Summary
content:
application/json:
schema:
type: object
properties:
summary:
type: string
/v1/predict/chat:
post:
operationId: predictChat
tags:
- Predict
summary: Predict - generative chat
description: >-
Nuclia Understanding API generative endpoint. Send a question with
context and receive a generated answer from the configured LLM. Streams
tokens back as they are produced. Authenticated with a NUA key.
security:
- nuaKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PredictChatRequest'
responses:
'200':
description: Generated answer (streamed)
content:
application/json:
schema:
type: object
/v1/predict/summarize:
post:
operationId: predictSummarize
tags:
- Predict
summary: Predict - summarize
description: Summarize supplied text using the Nuclia Understanding API.
security:
- nuaKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SummarizeRequest'
responses:
'200':
description: Summary
content:
application/json:
schema:
type: object
/v1/predict/rephrase:
post:
operationId: predictRephrase
tags:
- Predict
summary: Predict - rephrase
description: Rephrase a user question into an optimized search query.
security:
- nuaKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
question:
type: string
responses:
'200':
description: Rephrased query
content:
application/json:
schema:
type: object
/v1/predict/tokens:
get:
operationId: predictTokens
tags:
- Predict
summary: Predict - tokenize / NER
description: >-
Tokenize input text and return named entities (NER) detected by the
Nuclia Understanding API.
security:
- nuaKey: []
parameters:
- name: text
in: query
required: true
schema:
type: string
responses:
'200':
description: Tokens and entities
content:
application/json:
schema:
$ref: '#/components/schemas/TokensResponse'
/v1/predict/sentence:
get:
operationId: predictSentence
tags:
- Predict
summary: Predict - embed sentence
description: Return the embedding vector for a sentence using the configured semantic model.
security:
- nuaKey: []
parameters:
- name: text
in: query
required: true
schema:
type: string
responses:
'200':
description: Sentence embedding
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: number
/v1/predict/rerank:
post:
operationId: predictRerank
tags:
- Predict
summary: Predict - rerank
description: Rerank a set of retrieved passages against a question for improved relevance.
security:
- nuaKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: Reranked results
content:
application/json:
schema:
type: object
/v1/predict/models:
get:
operationId: listPredictModels
tags:
- Predict
summary: Predict - list models
description: List the generative and semantic models available to the account.
security:
- nuaKey: []
responses:
'200':
description: Available models
content:
application/json:
schema:
type: object
components:
parameters:
Kbid:
name: kbid
in: path
required: true
description: Unique identifier of the Knowledge Box.
schema:
type: string
Rid:
name: rid
in: path
required: true
description: Unique identifier of the resource.
schema:
type: string
responses:
Forbidden:
description: The API key does not grant the required role for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested object was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-NUCLIA-SERVICEACCOUNT
description: >-
Knowledge Box service account API key. Pass as
`X-NUCLIA-SERVICEACCOUNT: Bearer <token>`. Reader keys allow search/find/ask,
Writer keys allow ingestion and resource modification, Manager keys allow
administration. Public search endpoints may be called without a key when the
Knowledge Box is public.
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
OAuth2 / account bearer token obtained from the Nuclia authentication
service, used by the dashboard and management endpoints.
nuaKey:
type: apiKey
in: header
name: X-NUCLIA-NUAKEY
description: >-
Nuclia Understanding API (NUA) key. Pass as
`X-NUCLIA-NUAKEY: Bearer <token>` to call the /v1/predict endpoints.
schemas:
Error:
type: object
properties:
detail:
type: string
KnowledgeBox:
type: object
properties:
uuid:
type: string
slug:
type: string
title:
type: string
config:
type: object
Counters:
type: object
properties:
resources:
type: integer
paragraphs:
type: integer
fields:
type: integer
sentences:
type: integer
LabelSet:
type: object
properties:
title:
type: string
color:
type: string
multiple:
type: boolean
kind:
type: array
items:
type: string
labels:
type: array
items:
type: object
properties:
title:
type: string
CreateResourcePayload:
type: object
properties:
slug:
type: string
title:
type: string
summary:
type: string
icon:
type: string
usermetadata:
type: object
properties:
classifications:
type: array
items:
type: object
properties:
labelset:
type: string
label:
type: string
texts:
type: object
additionalProperties:
type: object
properties:
body:
type: string
format:
type: string
enum:
- PLAIN
- HTML
- MARKDOWN
- RST
links:
type: object
additionalProperties:
type: object
properties:
uri:
type: string
ResourceCreated:
type: object
properties:
uuid:
type: string
seqid:
type: integer
Resource:
type: object
properties:
id:
type: string
slug:
type: string
title:
type: string
summary:
type: string
created:
type: string
format: date-time
data:
type: object
extracted:
type: object
ResourceList:
type: object
properties:
resources:
type: array
items:
$ref: '#/components/schemas/Resource'
pagination:
type: object
properties:
page:
type: integer
size:
type: integer
total:
type: integer
SearchRequest:
type: object
required:
- query
properties:
query:
type: string
description: The natural-language or keyword query.
features:
type: array
description: Search features to enable (keyword, semantic, relations, fulltext).
items:
type: string
enum:
- keyword
- semantic
- relations
- fulltext
filters:
type: array
description: Label / metadata filters to constrain results.
items:
type: string
page_number:
type: integer
page_size:
type: integer
min_score:
type: number
rephrase:
type: boolean
SearchResults:
type: object
properties:
resources:
type: object
sentences:
type: object
paragraphs:
type: object
relations:
type: object
next_page:
type: boolean
FindResults:
type: object
properties:
resources:
type: object
description: Resources keyed by id, each with scored matching paragraphs.
relations:
type: object
total:
type: integer
next_page:
type: boolean
AskRequest:
type: object
required:
- query
properties:
query:
type: string
description: The natural-language question to answer.
context:
type: array
description: Prior conversation turns for multi-turn chat.
items:
type: object
properties:
author:
type: string
enum:
- USER
- NUCLIA
text:
type: string
filters:
type: array
items:
type: string
features:
type: array
items:
type: string
enum:
- keyword
- semantic
- relations
generative_model:
type: string
description: Override the generative model used to produce the answer.
prompt:
type: string
description: Custom prompt template wrapping the retrieved context.
citations:
type: boolean
rephrase:
type: boolean
max_tokens:
type: integer
AskResponse:
type: object
properties:
answer:
type: string
description: The generated answer text. Streamed incrementally when not synchronous.
relations:
type: object
retrieval_results:
$ref: '#/components/schemas/FindResults'
citations:
type: object
description: Mapping of cited resources / paragraphs supporting the answer.
learning_id:
type: string
status:
type: string
enum:
- success
- error
- no_context
SummarizeRequest:
type: object
properties:
resources:
type: array
items:
type: string
generative_model:
type: string
summary_kind:
type: string
enum:
- simple
- extended
PredictChatRequest:
type: object
required:
- question
properties:
question:
type: string
query_context:
type: array
items:
type: string
user_id:
type: string
generative_model:
type: string
TokensResponse:
type: object
properties:
tokens:
type: array
items:
type: object
properties:
text:
type: string
ner:
type: string
start:
type: integer
end:
type: integer
time:
type: number
security:
- apiKey: []
tags:
- name: Knowledge Boxes
description: Create, configure and inspect Knowledge Boxes and their label sets.
- name: Resources
description: Ingest and manage resources - files, text, links and conversations.
- name: Search
description: Hybrid search, find (RAG retrieval) and suggest over a Knowledge Box.
- name: Ask
description: Generative RAG answers, chat and summarization grounded in a Knowledge Box.
- name: Predict
description: Nuclia Understanding API (NUA) - generation, summarize, rephrase, rerank, embeddings and tokenization.