Are the API endpoints documented somewhere?

[JoghurtSommelier]

I'm looking to integrate the RAG chat in another service of mine and therefore would like to know which endpoints are available to use.

[clusterzx]

The RAG chat was not intended to be utilized outside the container. You have to expose the port of the RAG Server by hand to be able to even query it.

[the-Jack-D]

To follow on here, even though the question about RAG was answered, is the API documented somewhere? I'd like to disable automatic scanning and start scanning at night with CRON.

[clusterzx]

The RAG API is not documented sorry. As I said I did not intend to expose it. But of course you can do it by hand and look up the API Routes in the main.py

[the-Jack-D]

What I'd like to do his hit an endpoint at 1:00am that will tell to start processing documents. They can be added during the day, but processed at night.

[clusterzx]

You can definitely do this but you have to build your routine by yourself. If you expose the RAG port and use the api routes it is possible.

[FabricaBenedicta]

To jump into this same question, I have personal assistant that I have built using LETTA, and I'd like to be able to have my Letta Agent speak with my Paperless AI agent in Rag Chat and get answers on my documents without the need for me to open Rag Chat separately.

[clusterzx]

@the-Jack-D @FabricaBenedicta @JoghurtSommelier
Here is a OpenAPI Specific documentation for the API, but keep in mind you have to manually expose the port 8000 beforehand to query the API.

openapi: 3.0.3
info:
  title: RAGZ Document Search API
  version: "1.0.0"
  description: |
    RAGZ Document Search API for querying Paperless-NGX documents using hybrid (semantic + keyword) search with reranking.
    Features document indexing, update detection, cross-encoder reranking, and contextual retrieval for question answering.

paths:
  /search:
    post:
      summary: Search documents
      description: Perform a hybrid semantic + keyword search with reranking.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: A list of matching documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SearchResult'

  /context:
    post:
      summary: Get context for a question
      description: Retrieves relevant snippets from documents to answer a given question.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskQuestionRequest'
      responses:
        '200':
          description: Contextual information and sources
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  context:
                    type: string
                  sources:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'

  /status:
    get:
      summary: Get system status
      description: Returns current system and indexing status.
      responses:
        '200':
          description: System status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemStatus'

  /indexing/status:
    get:
      summary: Get indexing status
      description: Returns indexing status including progress, document count, and last update.
      responses:
        '200':
          description: Indexing status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexingStatus'

  /indexing/check:
    post:
      summary: Check for document updates
      description: Checks if new documents are available in Paperless-NGX.
      responses:
        '200':
          description: Update availability result
          content:
            application/json:
              schema:
                type: object
                properties:
                  needs_update:
                    type: boolean
                  message:
                    type: string

  /indexing/start:
    post:
      summary: Start indexing process
      description: Starts the document indexing process (background or foreground).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexingRequest'
      responses:
        '200':
          description: Indexing started or completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string

  /initialize:
    post:
      summary: Initialize the system
      description: Initialize models, load documents, and optionally start indexing.
      parameters:
        - in: query
          name: force
          schema:
            type: boolean
        - in: query
          name: background
          schema:
            type: boolean
      responses:
        '200':
          description: Initialization result
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data_loaded:
                    type: boolean
                  index_ready:
                    type: boolean
                  config_valid:
                    type: boolean

  /check_health:
    post:
      summary: Perform system health check
      description: Runs a full health diagnostic of the system components.
      responses:
        '200':
          description: Health status
          content:
            application/json:
              schema:
                type: object
                properties:
                  overall_status:
                    type: string
                  issues:
                    type: array
                    items:
                      type: string
                  recommendations:
                    type: array
                    items:
                      type: string

components:
  schemas:
    SearchRequest:
      type: object
      properties:
        query:
          type: string
        from_date:
          type: string
          format: date
          nullable: true
        to_date:
          type: string
          format: date
          nullable: true
        correspondent:
          type: string
          nullable: true
      required:
        - query

    AskQuestionRequest:
      type: object
      properties:
        question:
          type: string
        max_sources:
          type: integer
          default: 5
      required:
        - question

    IndexingRequest:
      type: object
      properties:
        force:
          type: boolean
          default: false
        background:
          type: boolean
          default: true

    SearchResult:
      type: object
      properties:
        title:
          type: string
        correspondent:
          type: string
        date:
          type: string
        score:
          type: number
        cross_score:
          type: number
        snippet:
          type: string
        doc_id:
          type: integer
          nullable: true

    IndexingStatus:
      type: object
      properties:
        running:
          type: boolean
        last_indexed:
          type: string
          nullable: true
        documents_count:
          type: integer
        up_to_date:
          type: boolean
        message:
          type: string

    SystemStatus:
      type: object
      properties:
        server_up:
          type: boolean
        data_loaded:
          type: boolean
        index_ready:
          type: boolean
        chroma_ready:
          type: boolean
        bm25_ready:
          type: boolean
        indexing_status:
          $ref: '#/components/schemas/IndexingStatus'