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.