Skip to main content

Generic RAG channel API

The channel API manages the documents of a Generic RAG application and searches them. The frontend uses it, and scripts and applications can too. This reference lists every endpoint of backend 0.3.3. It is for developers and administrators who manage an application's documents and know the channel configuration.

Calling the API​

The API is an application route of the type. Send requests to DIAL Core, at /v1/deployments/<application>/route/channel/..., with your DIAL credentials. DIAL Core forwards them to the backend's /channel/... with a per-request key and the application's ID.

<application> is the application's ID: its name in the DIAL Core configuration, or applications/<bucket>/<name> for an application in a bucket. The backend serves an interactive description of the API at /docs, which DIAL Core doesn't route.

curl -X POST "https://<DIAL_HOST>/v1/deployments/<APPLICATION_ID>/route/channel/documents?folder=reports" \
  -H "Api-Key: <DIAL_API_KEY>" \
  -F "attachment=@annual-2025.pdf;type=application/pdf" \
  -F 'metadata={"category": "annual-report", "published_on": "2025-03-01"}'

Documents​

A document is returned as this object:

FieldDescription
idThe document's ID in the channel, a number from 1
urlThe file in the application's bucket
display_nameThe folder and the original file name, such as reports/annual-2025.pdf
mime_typeThe file's MIME type
sizeThe file's size in bytes
metadataThe document's metadata
statuscreated, processing, processed, indexing, ready, or error
Method and pathDescription
GET /channel/documentsLists documents. See List documents.
POST /channel/documentsUploads a document. See Upload a document. Returns 201.
GET /channel/documents/exists?filename=<name>&folder=<folder>Returns {"exists": true} when a document with this name is in this folder
GET /channel/documents/{id}Returns a document
PUT /channel/documents/{id}Replaces the file, in the multipart field attachment, or the metadata, in the field metadata, or both. A new file is processed and indexed again.
DELETE /channel/documents/{id}Deletes the document, its file, chunks, and index records. Returns 204.
GET /channel/documents/{id}/downloadReturns the original file
PUT /channel/documents/{id}/metadataDeprecated. Sets the metadata from a JSON body. Use PUT /channel/documents/{id}.

List documents​

Query parameterDefaultDescription
offset0The number of documents to skip
limit25The most documents to return
sortNewest ID first<field> or <field>,asc or <field>,desc, and repeatable. Fields: id, display_name, mime_type, size, status, and sortable metadata fields.
<field>[eq]—Keeps documents whose string or string array field has this value. Repeat it for several values.
<field>[start], <field>[end]—Keeps documents whose date field is in this range

The response holds total_count, offset, limit, and results. Filters work only on filterable fields.

curl -g "https://<DIAL_HOST>/v1/deployments/<APPLICATION_ID>/route/channel/documents?limit=10&sort=published_on,desc&category[eq]=annual-report" \
  -H "Api-Key: <DIAL_API_KEY>"

Upload a document​

The request is multipart/form-data:

Part or parameterDescription
attachmentThe file. Its MIME type must be one that the channel's parsers accept.
metadataOptional. A JSON object that matches the channel's metadata schema
folder query parameterOptional. The folder to store the file in
overwrite query parametertrue replaces a document with the same name in the same folder. Otherwise such an upload fails.

The backend stores the file in the application's bucket and starts indexing. With background jobs, the response comes at once, with the status created. Otherwise it comes when indexing ends. An indexing failure then fails the request and sets the document's status to error. File names are compared without case.

Indexing​

Method and pathDescription
PUT /channel/documents/{id}/reindexIndexes the document again. See Reindex documents.
GET /channel/statsChunk statistics of every document
GET /channel/documents/{id}/statsChunk statistics of one document, page by page

Reindex documents​

Query parameterDefaultDescription
indexAll indexesAn index to rebuild. Repeat it for several.
forcefalsetrue processes the document again and rebuilds all indexes, ignoring index

A document whose status isn't processed or ready is processed first, whatever force is. The response is the document, with 202 when the work runs as a background job and 200 when it's done.

Chunk statistics​

Statistics count each document's text chunks, image chunks, and characters of text. documents_without_text counts documents with no text chunk. A ready document counted there was parsed without any text, for example a scanned PDF.

Search and retrieval​

Method and pathDescription
POST /channel/documents/searchFinds documents. See Search documents.
GET /channel/documents/search/schemaThe JSON schema of the search body for this channel
POST /channel/retrievalFinds chunks. See Retrieve chunks.
GET /channel/retrieval/schemaThe JSON schema of the retrieval body
GET /channel/metadataThe metadata schema, as schema, and the values in use in filterable string and string array fields, as dimensions
GET /channel/configThe channel configuration, with its channel_key

Search documents​

Document search uses the document indexes and returns documents, most relevant first.

FieldDefaultDescription
queryRequiredThe search query
limit5The most documents to return
indexesThe indexes with include_in_hybridThe document indexes to search, by name
matcherAll documentsfilters and top_n, as for the explicit selector

Retrieve chunks​

Retrieval runs the channel's retriever without an answer. The body has query and an optional retriever object, which is merged into the channel's retriever. It accepts the per-request options, such as top_k and a document selector.

{
  "query": "risk outlook",
  "retriever": {
    "document_selector": {"type": "exact_documents", "document_ids": [3, 7]}
  }
}

The response is a list, most relevant first. Each item has source_url, source_display_name, and source_metadata, and a result_type:

  • chunk. One chunk, with its fields: chunk_type (text or image), document_id, chunk_id, and metadata. A text chunk has text. An image chunk has image_type, mime_type, and content in base64.
  • combined. Several chunks in chunks. The classic retriever returns a text chunk with its page image this way.

Export and import​

Method and pathDescription
GET /channel/documents/{id}/exportDownloads the document as a bundle: the file, metadata, status, chunks, and index records, in MessagePack
POST /channel/documents/importImports a bundle from the multipart field attachment. overwrite=true replaces a document of the same name. Returns 201.
PUT /channel/exportStarts building the channel archive. Returns 202 and the status.
GET /channel/export/statusReturns the archive's status: pending, ready, error, or not_found
GET /channel/exportDownloads the archive. Returns 404 until it's ready.
POST /channel/importImports an archive from the multipart field attachment, of type application/zip. Returns 202.

The archive is a ZIP file with _channel.json, the channel configuration, and one bundle per document. The backend keeps it in the application's bucket, at export/<channel key>.zip, and deletes it at any change to the documents.

An archive imports only into a channel whose metadata_schema, parsers, and indexes are the same. Imported documents keep their chunks, index records, and status, so they aren't indexed again.

Building and importing an archive need background jobs. Without them, PUT /channel/export fails with "Could not create channel archive.", and POST /channel/import fails with 500.

Job endpoints​

/channel/jobs/... serves the backend's own job worker, which calls it through DIAL Core with DIAL_API_KEY. The endpoints stream their progress as server-sent events. Clients don't call them.

Further reading​