DIAL RAG API

DIAL RAG serves the Chat Completions endpoint of the Unified API. One endpoint runs the whole pipeline, or only its indexing or retrieval part, as the request asks. This reference is for developers who call DIAL RAG from an application or a script. It assumes you know attachments in custom_content. It is checked against DIAL RAG 0.43.0.

Request types

The request type is set in custom_fields.configuration.request.type.

Type	What runs	What the response holds
`rag`, the default	Indexing where needed, retrieval, and the answer	The answer, and one attachment per cited chunk
`indexing`	Indexing only	An index attachment per indexed document, and the indexing results
`retrieval`	Indexing where needed, and retrieval	The retrieved chunks and page images, as JSON

Documents are the attachments of all user messages in the request. A request whose last message has no text returns after indexing, with no answer and no retrieval results.

Configuration

custom_fields.configuration sets request settings for one request. It accepts every request setting at its path, plus the request object below. DIAL RAG validates the object and rejects unknown fields with 400. GET /openai/deployments/dial-rag/configuration returns its JSON schema.

Field	Default	Description
`request.type`	`rag`	See Request types.
`request.force_indexing`	`false`	Re-indexes the documents even when a usable index exists
`request.allow_indexing`	`true`	`false` uses only existing indexes. A missing or unusable index then fails the document; see Indexing errors.
`request.save_index_on_migration`	`true`	Saves an index that DIAL RAG migrated from an older format back to its location
`request.ignore_file_modification`	`false`	Uses an index even when the document's ETag or `Last-Modified` changed, for example after the file was moved or copied

Setting force_indexing to true with allow_indexing set to false fails the request with "Cannot force indexing when indexing is disabled."

Note

Any caller can change any request setting this way, including the models and the system prompt. DIAL Core still checks the caller's access to each model.

This example asks for retrieval with at most 2 page images:

{
  "custom_fields": {
    "configuration": {
      "request": {
        "type": "retrieval"
      },
      "qa_chain": {
        "chat_chain": {
          "num_page_images_to_use": 2
        }
      }
    }
  },
  "messages": [
    {
      "role": "user",
      "content": "What were the main risks in 2025?",
      "custom_content": {
        "attachments": [
          {"type": "application/pdf", "url": "files/<BUCKET>/reports/annual-2025.pdf"}
        ]
      }
    }
  ]
}

Index attachments

An index attachment points to an index file. DIAL RAG returns one for each document an indexing request indexed. A client can also send one with a document, to choose where that document's index is read from and written to.

{
  "type": "application/x.aidial-rag.index.v0",
  "url": "files/<BUCKET>/appdata/indexes/annual-2025.index",
  "reference_url": "files/<BUCKET>/reports/annual-2025.pdf"
}

Field	Description
`type`	`application/x.aidial-rag.index.v0`. Any other type that starts with `application/x.aidial-rag.index.` fails the request with "Unknown index type".
`url`	The index file in DIAL file storage. Inline `data` isn't supported.
`reference_url`	Required; without it, the request fails. The link of the document attachment in the same request that the index belongs to.

Your own location. DIAL Core must let DIAL RAG write there during the request. An application can share a folder of its bucket with DIAL RAG; see Sharing API.
The DIAL RAG bucket. An index attachment can point into DIAL RAG's own bucket only at the path DIAL RAG manages for that document. Any other path fails with "Index URL ... does not match the expected index path ...".
No index attachment. DIAL RAG uses the path it manages in its own bucket.

The index file's format isn't documented, and only DIAL RAG reads it.

Indexing requests

{
  "custom_fields": {"configuration": {"request": {"type": "indexing"}}},
  "messages": [
    {
      "role": "user",
      "content": "",
      "custom_content": {
        "attachments": [
          {"type": "application/pdf", "url": "files/<BUCKET>/reports/annual-2025.pdf"}
        ]
      }
    }
  ]
}

The response message has no content. Its attachments are:

One index attachment per document indexed without errors.
The indexing results. An attachment titled "Indexing results", of type application/x.aidial-rag.indexing-response+json. Its data is a JSON object with one field, indexing_result, that lists the documents that failed. See Indexing errors.

{
  "role": "assistant",
  "content": "",
  "custom_content": {
    "attachments": [
      {
        "type": "application/x.aidial-rag.index.v0",
        "url": "files/<DIAL_RAG_BUCKET>/dial-rag-index/<PATH>/index.bin",
        "reference_url": "files/<BUCKET>/reports/annual-2025.pdf"
      },
      {
        "type": "application/x.aidial-rag.indexing-response+json",
        "title": "Indexing results",
        "data": "{\"indexing_result\":{}}"
      }
    ]
  }
}

Retrieval requests

A retrieval request has the user's question in the last message. In a follow-up, the query model first rewrites the question, as in a rag request. The response message has no content and one attachment, titled "Retrieval response", of type application/x.aidial-rag.retrieval-response+json. Its data is a JSON object:

Field	Description
`chunks`	The retrieved chunks, most relevant first
`chunks[].attachment_url`	The link of the document attachment in the request that the chunk comes from
`chunks[].source.url`	A link to the chunk's source. For a PDF, it ends in `#page=<n>`.
`chunks[].source.display_name`	The document's name, as shown in the stages
`chunks[].text`	The chunk's text. It may be empty, for example for an image.
`chunks[].page.number`	The page number, from 1. `page` is `null` for formats without pages.
`chunks[].page.image_index`	The index of the page's image in `images`, or `null`
`images`	Page images of the retrieved chunks, as base64 PNG in `data`, with `mime_type` `image/png`
`indexing_results`	The documents that failed indexing in this request. See Indexing errors.

Only PDF documents, documents converted to PDF, and images have page images. The response includes at most num_page_images_to_use of them, 4 by default. When a document fails and ignore_document_loading_errors is false, the response holds only indexing_results.

Note

The field is indexing_result in an indexing response and indexing_results in a retrieval response.

RAG requests

A rag request streams the answer as message content. The model cites chunks, and DIAL RAG numbers the cited chunks [1], [2], and so on, in order of first citation. Each cited chunk becomes an attachment:

Field	Value
`type`	`text/markdown`
`title`	`[<n>] <document name>`
`data`	The chunk's text. For a page found by an image retriever, it's `[Image of the page <n>]`.
`reference_url`	The chunk's source. For a PDF, it ends in `#page=<n>`.

When a document fails and ignore_document_loading_errors is false, the content is the list of errors instead of an answer.

Indexing errors

indexing_result, or indexing_results, maps each failed document's link to its errors:

{
  "files/<BUCKET>/reports/annual-2025.pdf": {
    "errors": [
      {
        "message": "Document was modified",
        "type": "index_incompatible"
      }
    ]
  }
}

`type`	Meaning
`index_missing`	No index exists, and `allow_indexing` is `false`.
`index_incompatible`	The index doesn't match this version or these settings, or the document changed, and `allow_indexing` is `false`.
Absent	Any other error. Check `message`.

The message of an index_incompatible error names the cause, such as "Index settings mismatch: ..." or "Document was modified".

Response state

Every response sets custom_content.state to two objects. repository_digest identifies the source code version of the image. config_digest holds the effective configuration of the request and the parts that came from custom_fields.configuration and from commands.

Commands

A line of a user message that starts with a command is removed from the message and applied to the request. Commands are read from every user message in the conversation.

Command	Available	Effect
`/attach <url>`	Always	Adds a document by link, as if it were attached to the message
`/ignore_document_loading_errors`	Always	Sets `ignore_document_loading_errors` to `true`
`/model <deployment>`	With `ENABLE_DEBUG_COMMANDS`	Uses another chat model
`/query_model <deployment>`	With `ENABLE_DEBUG_COMMANDS`	Uses another query model, which must support tool calling
`/profile`	With `ENABLE_DEBUG_COMMANDS`	Adds a CPU profile in a Profiler stage

Without ENABLE_DEBUG_COMMANDS, DIAL RAG still removes the lines of debug commands but ignores them.

Request types​

Configuration​

Index attachments​

Indexing requests​

Retrieval requests​

RAG requests​

Indexing errors​

Response state​

Commands​

Further reading​