File upload and indexing

SREDSimplify uses a two-phase upload flow so browser clients can upload file bytes directly to Cloudflare R2 without proxying the payload through the app server.

Endpoint map

Endpoint	Purpose
POST /api/v1/projects/{projectId}/files/presign	Reserve storage and get direct-upload URLs
POST /api/v1/projects/{projectId}/files/{fileId}/confirm	Confirm a completed upload and trigger indexing
GET /api/v1/projects/{projectId}/files	List project files and their status
POST /api/v1/projects/{projectId}/files/preview-word	Create a short-lived preview URL for generated DOCX content
DELETE /api/v1/projects/{projectId}/files/{fileId}	Delete a file

Step 1: Request presigned upload URLs

Request body:

{
  "files": [
    {
      "filename": "evidence.pdf",
      "contentType": "application/pdf",
      "fileSize": 123456
    }
  ]
}

Each result contains:

Field	Meaning
fileId	Backend-assigned UUID for later confirmation
uploadUrl	Presigned PUT URL to R2
objectKey	R2 object key
expiresAt	Expiration timestamp in epoch millis

The backend sums the requested file sizes and performs quota-aware reservation before returning upload URLs.

Step 2: Upload directly to R2

The frontend uploads the bytes directly to the returned uploadUrl.

This stage does not mark the file usable yet. After a successful PUT, the client must call the confirm endpoint.

Step 3: Confirm upload completion

Confirmation body is optional, but may include the R2 etag:

{
  "etag": "\"abc123\""
}

Confirmation changes the file from a pending upload record into a confirmed file metadata record and kicks off indexing work.

File statuses

Upload status

• PENDING: presigned URL issued, waiting for upload completion
• CONFIRMED: upload confirmed by the client
• FAILED: upload failed or reservation expired

Index status

• PENDING: waiting for indexing work to start
• INDEXING: indexing in progress
• READY: usable for AI runs
• FAILED: indexing failed

The workspace should treat only READY files as valid run context.

Listing files

GET /api/v1/projects/{projectId}/files returns confirmed file records with:

• original filename
• content type
• file size
• upload timestamp
• upload/index statuses
• optional index error

This is the source of truth for frontend polling while indexing is active.

Word preview flow

POST /api/v1/projects/{projectId}/files/preview-word accepts:

{
  "filename": "draft.docx",
  "contentBase64": "..."
}

The backend stores the generated DOCX temporarily and returns a short-lived preview URL intended for Office-style preview flows.

Delete behavior

DELETE /api/v1/projects/{projectId}/files/{fileId} removes the file metadata and underlying object for the authenticated owner path.