feat(documents): Add v2 upload endpoints

backend/app/api/docs/documents/register_v2.md

@@ -0,0 +1,7 @@
+Register a document that was uploaded to the pre-signed URL from `POST /api/v2/documents/upload-url`.
+
+Final step of the v2 upload flow. Pass the `document_id` returned by the upload URL endpoint together with the filename; the document row is created and the response carries a fresh signed URL for reading the file back.
+
+Errors: `400` if no file was uploaded for that `document_id` (or the extension is unsupported), `413` if the uploaded file exceeds 25 MB (the object is deleted), `409` if the `document_id` was already registered — request a new upload URL in that case.
+
+Document transformation is not available on v2. Use `POST /api/v1/documents` if you need a `target_format` conversion.

backend/app/api/docs/documents/upload_url_v2.md

@@ -0,0 +1,9 @@
+Request a pre-signed URL to upload a document straight to Kaapi's object storage.
+
+Step 1 of the v2 upload flow:
+
+1. `POST /api/v2/documents/upload-url` with the filename — returns a `document_id` and an `upload_url`.
+2. `PUT` the raw file bytes to `upload_url` (no auth header, no form encoding).
+3. `POST /api/v2/documents` with the same `document_id` and `filename` to register the document.
+
+The filename extension is validated here, so an unsupported file type fails before any upload. Nothing is persisted at this step: the `document_id` only becomes a document once you register it. `upload_url` is valid for `expires_in` seconds; request a new one if it lapses. Maximum file size is 25 MB, enforced at registration.

backend/app/api/main.py

@@ -12,6 +12,7 @@
     cron,
     doc_transformation_job,
     documents,
+    documents_v2,
     evaluations,
     features,
     fine_tuning,
@@ -89,8 +90,10 @@
 
 
 # v2 API surface (mounted at settings.API_V2_STR). Only the endpoints that differ
-# from v1 live here — currently the judged run trigger. Everything else stays v1.
+# from v1 live here — currently the judged run trigger and the pre-signed document
+# upload flow. Everything else stays v1.
 api_v2_router = APIRouter()
+api_v2_router.include_router(documents_v2.router)
 api_v2_router.include_router(evaluations_v2_router)
 api_v2_router.include_router(evaluations_dataset_v2_router)
 api_v2_router.include_router(evaluations_prompt_improvement_v2_router)

backend/app/api/routes/documents_v2.py

@@ -0,0 +1,125 @@
+"""v2 document upload: pre-signed PUT to storage, then registration. No transformation."""
+
+import logging
+from pathlib import Path
+from uuid import uuid4
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.api.deps import AuthContextDep, SessionDep
+from app.api.permissions import Permission, require_permission
+from app.core.cloud import get_cloud_storage
+from app.core.cloud.storage import SimpleStorageName
+from app.crud import DocumentCrud
+from app.models import (
+    Document,
+    DocumentPublic,
+    DocumentRegisterRequest,
+    DocumentUploadResponse,
+    DocumentUploadURLRequest,
+    DocumentUploadURLResponse,
+)
+from app.services.documents.helpers import (
+    validate_filename_format,
+    verify_uploaded_object,
+)
+from app.utils import APIResponse, load_description
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/documents", tags=["Documents v2"])
+
+UPLOAD_URL_EXPIRY_SECONDS = 3600
+
+
+@router.post(
+    "/upload-url",
+    description=load_description("documents/upload_url_v2.md"),
+    response_model=APIResponse[DocumentUploadURLResponse],
+    dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
+)
+def create_upload_url(
+    session: SessionDep,
+    current_user: AuthContextDep,
+    request: DocumentUploadURLRequest,
+) -> APIResponse[DocumentUploadURLResponse]:
+    validate_filename_format(request.filename)
+
+    storage = get_cloud_storage(session=session, project_id=current_user.project_.id)
+    document_id = uuid4()
+    key = Path(storage.storage_path) / str(document_id)
+    upload_url = storage.get_signed_upload_url(
+        key.as_posix(),
+        expires_in=UPLOAD_URL_EXPIRY_SECONDS,
+    )
+
+    logger.info(
+        f"[create_upload_url] Upload URL issued | "
+        f"document_id: {document_id}, project_id: {current_user.project_.id}"
+    )
+
+    return APIResponse[DocumentUploadURLResponse].success_response(
+        DocumentUploadURLResponse(
+            document_id=document_id,
+            upload_url=upload_url,
+            expires_in=UPLOAD_URL_EXPIRY_SECONDS,
+        )
+    )
+
+
+@router.post(
+    "",
+    description=load_description("documents/register_v2.md"),
+    status_code=201,
+    response_model=APIResponse[DocumentUploadResponse],
+    dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))],
+)
+def register_document(
+    session: SessionDep,
+    current_user: AuthContextDep,
+    request: DocumentRegisterRequest,
+) -> APIResponse[DocumentUploadResponse]:
+    validate_filename_format(request.filename)
+
+    crud = DocumentCrud(session, current_user.project_.id)
+    if crud.exists(request.document_id):
+        logger.warning(
+            f"[register_document] Document already registered | "
+            f"document_id: {request.document_id}, project_id: {current_user.project_.id}"
+        )
+        raise HTTPException(
+            status_code=409,
+            detail="This document_id is already registered. Request a new upload URL.",
+        )
+
+    storage = get_cloud_storage(session=session, project_id=current_user.project_.id)
+    key = Path(storage.storage_path) / str(request.document_id)
+    object_store_url = str(SimpleStorageName(key.as_posix()))
+
+    file_size_kb = verify_uploaded_object(
+        storage=storage,
+        object_store_url=object_store_url,
+        document_id=request.document_id,
+    )
+
+    document = crud.update(
+        Document(
+            id=request.document_id,
+            fname=request.filename,
+            file_size_kb=file_size_kb,
+            object_store_url=object_store_url,
+            project_id=current_user.project_.id,
+        )
+    )
+
+    document_schema = DocumentPublic.model_validate(document, from_attributes=True)
+    document_schema.signed_url = storage.get_signed_url(document.object_store_url)
+
+    logger.info(
+        f"[register_document] Document registered | "
+        f"document_id: {document.id}, project_id: {current_user.project_.id}, size_kb: {file_size_kb}"
+    )
+
+    return APIResponse[DocumentUploadResponse].success_response(
+        DocumentUploadResponse(**document_schema.model_dump())
+    )

backend/app/core/cloud/storage.py

@@ -155,6 +155,16 @@ def get_signed_url(self, url: str, expires_in: int = 3600) -> str:
         """Generate a signed URL with an optional expiry"""
         pass
 
+    @abstractmethod
+    def get_signed_upload_url(
+        self,
+        key: str,
+        content_type: str | None = None,
+        expires_in: int = 3600,
+    ) -> str:
+        """Generate a signed URL the client can upload (PUT) to directly"""
+        pass
+
     @abstractmethod
     def delete(self, url: str) -> None:
         """Delete a file from storage"""
@@ -285,6 +295,42 @@ def get_signed_url(self, url: str, expires_in: int = 3600) -> str:
             )
             raise CloudStorageError(f'AWS Error: "{err}" ({url})') from err
 
+    def get_signed_upload_url(
+        self,
+        key: str,
+        content_type: str | None = None,
+        expires_in: int = 3600,
+    ) -> str:
+        """
+        Generate a signed S3 URL the client can PUT a file to.
+        content_type, when set, is enforced: the client must send a matching header.
+        """
+        expires_in = min(expires_in, self.MAX_SIGNED_URL_EXPIRY)
+
+        name = SimpleStorageName(key)
+        params: dict[str, str] = asdict(name)
+        if content_type:
+            params["ContentType"] = content_type
+
+        try:
+            signed_url = self.aws.client.generate_presigned_url(
+                "put_object",
+                Params=params,
+                ExpiresIn=expires_in,
+            )
+            logger.info(
+                f"[AmazonCloudStorage.get_signed_upload_url] Signed upload URL generated | "
+                f"{{'project_id': '{self.project_id}', 'bucket': '{_mask(name.Bucket)}', 'key': '{_mask(name.Key)}', 'expires_in': {expires_in}}}"
+            )
+            return signed_url
+        except ClientError as err:
+            logger.error(
+                f"[AmazonCloudStorage.get_signed_upload_url] AWS presign error | "
+                f"{{'project_id': '{self.project_id}', 'bucket': '{_mask(name.Bucket)}', 'key': '{_mask(name.Key)}', 'error': '{str(err)}'}}",
+                exc_info=True,
+            )
+            raise CloudStorageError(f'AWS Error: "{err}" ({key})') from err
+
     def delete(self, url: str) -> None:
         name = SimpleStorageName.from_url(url)
         kwargs = asdict(name)

backend/app/crud/document/document.py

@@ -33,6 +33,10 @@ def read_one(self, doc_id: UUID) -> Document:
 
         return result
 
+    def exists(self, doc_id: UUID) -> bool:
+        # Ignores deleted_at and project scope: the PK stays taken after a soft delete.
+        return self.session.get(Document, doc_id) is not None
+
     def read_many(
         self,
         skip: int | None = None,

backend/app/models/__init__.py

@@ -86,7 +86,10 @@
     DocTransformationJobsPublic,
     Document,
     DocumentPublic,
+    DocumentRegisterRequest,
     DocumentUploadResponse,
+    DocumentUploadURLRequest,
+    DocumentUploadURLResponse,
     TransformationJobInfo,
     TransformedDocumentPublic,
 )

backend/app/models/document.py

@@ -117,6 +117,33 @@ class DocumentUploadResponse(DocumentPublic):
     transformation_job: TransformationJobInfo | None = None
 
 
+class DocumentUploadURLRequest(SQLModel):
+    filename: str = Field(
+        min_length=1,
+        max_length=255,
+        description="Original filename including its extension, e.g. report.pdf",
+    )
+
+
+class DocumentUploadURLResponse(SQLModel):
+    document_id: UUID = Field(
+        description="Identifier to register the document with once the upload completes"
+    )
+    upload_url: str = Field(description="Pre-signed URL to PUT the file contents to")
+    expires_in: int = Field(description="Lifetime of the upload URL in seconds")
+
+
+class DocumentRegisterRequest(SQLModel):
+    document_id: UUID = Field(
+        description="The document_id returned by the upload URL endpoint"
+    )
+    filename: str = Field(
+        min_length=1,
+        max_length=255,
+        description="Original filename including its extension, e.g. report.pdf",
+    )
+
+
 class DocTransformationJobPublic(SQLModel):
     job_id: UUID
     source_document_id: UUID

backend/app/services/documents/helpers.py

@@ -2,11 +2,13 @@
 from typing import Optional, Tuple, Iterable, Union
 from uuid import UUID
 
+from botocore.exceptions import ClientError
 from fastapi import HTTPException, UploadFile
 from sqlmodel import Session
 
-from app.core.cloud.storage import CloudStorage
+from app.core.cloud.storage import CloudStorage, CloudStorageError
 
+from app.services.collections.helpers import MAX_DOC_SIZE_MB
 from app.services.doctransform.registry import (
     get_available_transformers,
     get_file_format,
@@ -87,6 +89,59 @@ def calculate_file_size(file: UploadFile) -> float:
     return round(size_bytes / 1024)
 
 
+def validate_filename_format(filename: str) -> str:
+    """Resolve document format from the extension; HTTPException(400) if unsupported."""
+    try:
+        return get_file_format(filename)
+    except ValueError as e:
+        logger.warning(
+            f"[validate_filename_format] Unsupported file extension | filename: {filename}"
+        )
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+def verify_uploaded_object(
+    *,
+    storage: CloudStorage,
+    object_store_url: str,
+    document_id: UUID,
+) -> float:
+    """Confirm the uploaded object exists and fits the size budget; return size in KB."""
+    try:
+        file_size_kb = storage.get_file_size_kb(object_store_url)
+    except CloudStorageError as e:
+        # Only a missing object is the client's fault; other S3 failures stay 500.
+        cause = e.__cause__
+        if not (
+            isinstance(cause, ClientError)
+            and cause.response.get("Error", {}).get("Code") in ("404", "NoSuchKey")
+        ):
+            raise
+        logger.warning(
+            f"[verify_uploaded_object] No object found at expected key | document_id: {document_id}"
+        )
+        raise HTTPException(
+            status_code=400,
+            detail="No uploaded file found for this document_id. Upload the file to the "
+            "pre-signed URL before registering it.",
+        )
+
+    file_size_mb = file_size_kb / 1024
+    if file_size_mb > MAX_DOC_SIZE_MB:
+        storage.delete(object_store_url)
+        logger.warning(
+            f"[verify_uploaded_object] Document size exceeds limit | "
+            f"document_id: {document_id}, size_mb: {round(file_size_mb, 2)}, max_size_mb: {MAX_DOC_SIZE_MB}"
+        )
+        raise HTTPException(
+            status_code=413,
+            detail=f"Document size ({round(file_size_mb, 2)} MB) exceeds the maximum allowed size of {MAX_DOC_SIZE_MB} MB. "
+            f"Please upload a smaller file.",
+        )
+
+    return file_size_kb
+
+
 def pre_transform_validation(
     *,
     src_filename: str,
@@ -102,10 +157,7 @@ def pre_transform_validation(
     Returns: (source_format, actual_transformer_or_none)
     Raises: HTTPException(400) on client errors.
     """
-    try:
-        source_format = get_file_format(src_filename)
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
+    source_format = validate_filename_format(src_filename)
 
     actual_transformer: Optional[str] = None
     if target_format:

backend/app/tests/api/routes/documents/conftest.py

@@ -1,6 +1,9 @@
+import os
+
 import pytest
 from starlette.testclient import TestClient
 
+from app.core.config import settings
 from app.tests.utils.auth import TestAuthContext
 from app.tests.utils.document import WebCrawler
 
@@ -9,3 +12,12 @@
 def crawler(client: TestClient, user_api_key: TestAuthContext) -> WebCrawler:
     """Provides a WebCrawler instance for document API testing."""
     return WebCrawler(client, user_api_key=user_api_key)
+
+
+@pytest.fixture(scope="class")
+def aws_credentials() -> None:
+    os.environ["AWS_ACCESS_KEY_ID"] = "testing"
+    os.environ["AWS_SECRET_ACCESS_KEY"] = "testing"
+    os.environ["AWS_SECURITY_TOKEN"] = "testing"
+    os.environ["AWS_SESSION_TOKEN"] = "testing"
+    os.environ["AWS_DEFAULT_REGION"] = settings.AWS_DEFAULT_REGION