From f6314a1eeb3a1d7cec6e1c1d7bd44172133478d8 Mon Sep 17 00:00:00 2001 From: Gonzalo Tixilima Date: Mon, 6 Jul 2026 13:33:56 -0500 Subject: [PATCH] FLCRM-21226: Document RAG document selections API Adds OpenAPI documentation for the new offline RAG endpoints introduced alongside the reference-document selection feature: - GET /v2/forms/{form_id}/rag_document_selections.json - PATCH /v2/forms/{form_id}/rag_document_selections/{id}.json Also documents the new rag_enabled, rag_bundle_version, and rag_bundle_download_url fields on the Form response object. New schemas: RagDocumentSelection, RagDocumentSelectionsResponse, RagDocumentSelectionResponse, RagDocumentSelectionUpdateRequest, ForbiddenResponse. --- reference/rest-api.json | 265 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) diff --git a/reference/rest-api.json b/reference/rest-api.json index 7d420ce..1f9bae7 100644 --- a/reference/rest-api.json +++ b/reference/rest-api.json @@ -3453,6 +3453,24 @@ }, "assignment_enabled": { "type": "boolean" + }, + "rag_enabled": { + "type": "boolean", + "description": "Whether offline RAG is enabled for any reference documents in this form" + }, + "rag_bundle_version": { + "type": [ + "string", + "null" + ], + "description": "The active bundle UUID compiled for offline use" + }, + "rag_bundle_download_url": { + "type": [ + "string", + "null" + ], + "description": "The secure CDN pre-signed download URL for the bundled RAG package" } } } @@ -4337,6 +4355,119 @@ } } } + }, + "RagDocumentSelection": { + "type": "object", + "description": "A form's reference document and whether it is included in the offline RAG bundle", + "properties": { + "id": { + "type": "integer", + "description": "Selection record ID" + }, + "form_resource_id": { + "type": "string", + "description": "The form this selection belongs to" + }, + "attachment_resource_id": { + "type": "string", + "description": "The reference file (attachment) this selection points to" + }, + "rag_enabled": { + "type": "boolean", + "description": "Whether this document is included in the form's offline RAG bundle" + }, + "filename": { + "type": [ + "string", + "null" + ], + "description": "The reference file's filename" + }, + "document_title": { + "type": [ + "string", + "null" + ], + "description": "Display title for the document" + }, + "processing_status": { + "type": "string", + "description": "Processing state of the document", + "enum": [ + "pending", + "processing", + "ready", + "failed" + ] + }, + "processing_error": { + "type": [ + "string", + "null" + ], + "description": "Error message if processing_status is failed" + }, + "chunk_count": { + "type": "integer", + "description": "Number of chunks extracted from this document" + }, + "processed_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "ISO 8601 timestamp of the last successful processing run" + }, + "file_size": { + "type": "integer", + "description": "Size of the reference file in bytes" + } + } + }, + "RagDocumentSelectionsResponse": { + "type": "object", + "description": "Response containing the list of reference document selections for a form", + "properties": { + "document_selections": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RagDocumentSelection" + } + } + } + }, + "RagDocumentSelectionResponse": { + "type": "object", + "description": "Response containing a single reference document selection", + "properties": { + "document_selection": { + "$ref": "#/components/schemas/RagDocumentSelection" + } + } + }, + "RagDocumentSelectionUpdateRequest": { + "type": "object", + "description": "Request body for enabling or disabling a reference document for offline RAG", + "required": [ + "rag_enabled" + ], + "properties": { + "rag_enabled": { + "type": "boolean", + "description": "Whether to include this document in the form's offline RAG bundle" + } + } + }, + "ForbiddenResponse": { + "type": "object", + "description": "Forbidden error response", + "properties": { + "error": { + "type": "string", + "example": "Forbidden" + } + } } } }, @@ -13827,6 +13958,140 @@ }, "deprecated": false } + }, + "/v2/forms/{form_id}/rag_document_selections.json": { + "get": { + "summary": "List a form's RAG document selections", + "description": "Returns every reference document attached to the form, merged with its current offline RAG selection state (enabled/disabled, processing status, chunk count). Requires the rag-offline-sync feature flag.", + "operationId": "rag-document-selections-index", + "parameters": [ + { + "name": "form_id", + "in": "path", + "description": "Form ID", + "schema": { + "type": "string" + }, + "required": true + }, + { + "name": "Accept", + "in": "header", + "schema": { + "type": "string", + "default": "application/json" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RagDocumentSelectionsResponse" + } + } + } + }, + "403": { + "description": "Forbidden — the rag-offline-sync feature flag is disabled for this user/organization", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + } + }, + "deprecated": false + } + }, + "/v2/forms/{form_id}/rag_document_selections/{id}.json": { + "patch": { + "summary": "Enable or disable a reference document for offline RAG", + "description": "Toggles whether a specific reference document (attachment) is included in the form's offline RAG bundle. Enabling enqueues background processing of the document; disabling enqueues cleanup of its chunks. Enforces a 15MB per-file limit and a 50MB cumulative limit across all enabled documents for the form. Requires the rag-offline-sync feature flag.", + "operationId": "rag-document-selections-update", + "parameters": [ + { + "name": "form_id", + "in": "path", + "description": "Form ID", + "schema": { + "type": "string" + }, + "required": true + }, + { + "name": "id", + "in": "path", + "description": "Attachment (reference file) resource ID", + "schema": { + "type": "string" + }, + "required": true + }, + { + "name": "Accept", + "in": "header", + "schema": { + "type": "string", + "default": "application/json" + } + }, + { + "name": "Content-Type", + "in": "header", + "schema": { + "type": "string", + "default": "application/json" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RagDocumentSelectionUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RagDocumentSelectionResponse" + } + } + } + }, + "403": { + "description": "Forbidden — the feature flag is disabled, or the attachment does not belong to this form", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + }, + "422": { + "description": "Unprocessable Entity — the file exceeds the 15MB individual limit, enabling it would exceed the 50MB cumulative budget, or the reference file metadata could not be retrieved", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorResponse" + } + } + } + } + }, + "deprecated": false + } } }, "x-readme": {