diff --git a/backend/app/api/docs/documents/info.md b/backend/app/api/docs/documents/info.md index 2ecf4a37b..527a2308d 100644 --- a/backend/app/api/docs/documents/info.md +++ b/backend/app/api/docs/documents/info.md @@ -1 +1 @@ -Retrieve all information about a given document. +Retrieve all information about a given document. If you set the ``include_url`` parameter to true, a signed URL will be included in the response, which is a clickable link to access the retrieved document. If you don't set it to true, the URL will not be included in the response. diff --git a/backend/app/api/docs/documents/job_info.md b/backend/app/api/docs/documents/job_info.md new file mode 100644 index 000000000..c70e42bfa --- /dev/null +++ b/backend/app/api/docs/documents/job_info.md @@ -0,0 +1 @@ +Get the status and details of a document transformation job. If you set the ``include_url`` parameter to true, a signed URL will be included in the response, which is a clickable link to access the transformed document if the job has been successful. If you don't set it to true, the URL will not be included in the response. diff --git a/backend/app/api/docs/documents/job_list.md b/backend/app/api/docs/documents/job_list.md new file mode 100644 index 000000000..f85ca99ad --- /dev/null +++ b/backend/app/api/docs/documents/job_list.md @@ -0,0 +1 @@ +Get the status and details of multiple document transformation jobs by IDs. If you set the ``include_url`` parameter to true, a signed URL will be included in the response, which is a clickable link to access the transformed document for successful jobs. If you don't set it to true, the URL will not be included in the response. diff --git a/backend/app/api/docs/documents/list.md b/backend/app/api/docs/documents/list.md index 793d29b0f..110e931c9 100644 --- a/backend/app/api/docs/documents/list.md +++ b/backend/app/api/docs/documents/list.md @@ -1 +1 @@ -List documents uploaded to the AI platform. +List documents uploaded to the AI platform. If you set the ``include_url`` parameter to true, a signed URL will be included in the response, which is a clickable link to access the retrieved documents. If you don't set it to true, the URL will not be included in the response. diff --git a/backend/app/api/docs/documents/upload.md b/backend/app/api/docs/documents/upload.md index 87e46d473..cc4ad9bf5 100644 --- a/backend/app/api/docs/documents/upload.md +++ b/backend/app/api/docs/documents/upload.md @@ -2,6 +2,7 @@ Upload a document to the AI platform. - If only a file is provided, the document will be uploaded and stored, and its ID will be returned. - If a target format is specified, a transformation job will also be created to transform document into target format in the background. The response will include both the uploaded document details and information about the transformation job. +- If a callback URL is provided, you will receive a notification at that URL once the document transformation job is completed. ### Supported Transformations diff --git a/backend/app/api/routes/doc_transformation_job.py b/backend/app/api/routes/doc_transformation_job.py index dac5e131a..dd5f98827 100644 --- a/backend/app/api/routes/doc_transformation_job.py +++ b/backend/app/api/routes/doc_transformation_job.py @@ -1,16 +1,15 @@ from uuid import UUID import logging -from fastapi import APIRouter, HTTPException, Query, Path +from fastapi import APIRouter, Query, Path from app.api.deps import CurrentUserOrgProject, SessionDep from app.crud import DocTransformationJobCrud, DocumentCrud from app.models import ( DocTransformationJobPublic, DocTransformationJobsPublic, - TransformedDocumentPublic, ) -from app.utils import APIResponse +from app.utils import APIResponse, load_description from app.services.documents.helpers import build_job_schema, build_job_schemas from app.core.cloud import get_cloud_storage @@ -21,7 +20,7 @@ @router.get( "/{job_id}", - description="Get the status and details of a document transformation job.", + description=load_description("documents/job_info.md"), response_model=APIResponse[DocTransformationJobPublic], ) def get_transformation_job( @@ -53,7 +52,7 @@ def get_transformation_job( @router.get( "/", - description="Get the status and details of multiple document transformation jobs by IDs.", + description=load_description("documents/job_list.md"), response_model=APIResponse[DocTransformationJobsPublic], ) def get_multiple_transformation_jobs( diff --git a/backend/app/api/routes/documents.py b/backend/app/api/routes/documents.py index 3b93946ca..a1c2d89dd 100644 --- a/backend/app/api/routes/documents.py +++ b/backend/app/api/routes/documents.py @@ -23,6 +23,7 @@ DocumentUploadResponse, Message, TransformationJobInfo, + DocTransformationJobPublic, ) from app.services.collections.helpers import pick_service_for_documennt from app.services.documents.helpers import ( @@ -36,6 +37,25 @@ logger = logging.getLogger(__name__) router = APIRouter(prefix="/documents", tags=["documents"]) +doctransformation_callback_router = APIRouter() + + +@doctransformation_callback_router.post( + "{$callback_url}", + name="doctransformation_callback", +) +def doctransformation_callback_notification( + body: APIResponse[DocTransformationJobPublic], +): + """ + Callback endpoint specification for document transformation. + + The callback will receive: + - On success: APIResponse with success=True and data containing DocTransformationJobPublic + - On failure: APIResponse with success=False and error message + - metadata field will always be included if provided in the request + """ + ... @router.get( @@ -73,6 +93,7 @@ def list_docs( "/", description=load_description("documents/upload.md"), response_model=APIResponse[DocumentUploadResponse], + callbacks=doctransformation_callback_router.routes, ) async def upload_doc( session: SessionDep,