API Reference

The MS Word Integration provides REST API endpoints for managing external editing sessions, handling file uploads, and retrieving session information.

Base URL

All endpoints are prefixed with /api-v3/report/external-edit/

Endpoints

GET /{lab_report_id}

Retrieve existing edit session information for a lab report.

Parameters:

• lab_report_id (path): ID of the lab report

Response:

{
  "id": 123,
  "word_file_path": "s3://bucket/path/to/document.docx",
  "pdf_file_path": "s3://bucket/path/to/document.pdf",
  "auth_token": "jwt_token_here",
  "is_active": 1,
  "author_name": "Dr. Smith",
  "updated_at": 1640995200000
}

Status Codes:

• 200: Success
• 404: No active session found

POST /{lab_report_id}

Create a new external edit session.

Parameters:

• lab_report_id (path): ID of the lab report

Request Body:

{
  "template_id": 456,
  "word_s3_filepath": "s3://bucket/templates/radiology_template.docx"
}

Response:

{
  "edit_id": 123,
  "auth_token": "jwt_token_here",
  "template_path": "presigned_s3_url_for_download"
}

Status Codes:

• 200: Session created successfully
• 400: Invalid request or template not found
• 409: Active session already exists

PUT /{edit_id}

End an external edit session.

Parameters:

• edit_id (path): ID of the edit session

Response:

{
  "message": "Session has been inactivated"
}

Status Codes:

• 200: Session ended successfully
• 403: Unauthorized (not the session author)
• 404: Session not found

POST /agent/{edit_id}

Upload edited Word and PDF files. This is the endpoint used by the desktop client (crelio_client) when it detects a file save event.

Parameters:

• edit_id (path): ID of the edit session

Request Body (Form Data):

• word_file: The edited Word document (.docx)
• pdf_file: The converted PDF document (.pdf)

Response:

{
  "message": "Files uploaded and linked successfully",
  "word_s3_path": "s3://bucket/path/to/uploaded.docx",
  "pdf_s3_path": "s3://bucket/path/to/uploaded.pdf"
}

Status Codes:

• 200: Files uploaded successfully
• 400: Invalid file types or missing files
• 403: Unauthorized or session inactive

Authentication

All endpoints require authentication via JWT token passed in the Authorization header:

Authorization: Bearer <jwt_token>

The JWT token is generated when creating an edit session and contains:

• user_id: ID of the lab user
• lab_report_id: ID of the report being edited
• session_id: ID of the edit session
• exp: Token expiration timestamp

Error Responses

All endpoints return errors in the following format:

{
  "code": 400,
  "message": "Error description",
  "details": "Additional error information"
}

Common Error Codes

• 400: Bad Request (invalid parameters)
• 401: Unauthorized (invalid/missing token)
• 403: Forbidden (insufficient permissions)
• 404: Not Found (resource doesn't exist)
• 409: Conflict (session already active)
• 500: Internal Server Error

File Upload Specifications

Word Document (.docx)

• Maximum Size: 50MB
• Content Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
• Validation: File signature verification

PDF Document (.pdf)

• Maximum Size: 100MB
• Content Type: application/pdf
• Validation: PDF header verification

Rate Limiting

• Session Creation: 10 requests per minute per user
• File Upload: 5 requests per minute per session
• Session Retrieval: 60 requests per minute per user

WebSocket Integration

For real-time updates on session status, the system integrates with WebSocket channels:

• Channel: external_edit_{lab_report_id}
• Events:
  • session_created: New session started
  • session_ended: Session completed
  • authorship_changed: Author changed
  • files_uploaded: Files successfully uploaded

Example Usage

Creating a Session

const response = await fetch('/api-v3/report/external-edit/12345', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template_id: 456,
    word_s3_filepath: 's3://bucket/templates/template.docx'
  })
});

const data = await response.json();
if (data.edit_id) {
  // Launch Word with the presigned URL
  window.open(`winword://${data.auth_token}^${data.edit_id}^${data.template_path}`, '_blank');
}

Uploading Files

The desktop client (crelio_client) performs uploads using Python's requests library. The endpoint used is:

POST /api-v3/report/external-edit/agent/{edit_id}

Example from crelio_client/services/word_watch/uplaoder.py:

import requests

def upload_files(edit_id: str, auth_token: str, word_path: str, pdf_path: str):
    url = f"https://your-backend/api-v3/report/external-edit/agent/{edit_id}"
    files = {
        "word_file": ("report.docx", open(word_path, "rb"), "application/vnd.openxmlformats-officedocument.wordprocessingml.document"),
        "pdf_file": ("report.pdf", open(pdf_path, "rb"), "application/pdf"),
    }
    headers = {
        "Authorization": f"Bearer {auth_token}",
        "X-IS-EXTERNAL-EDIT-REQUEST": "true",
    }
    response = requests.post(url, files=files, headers=headers)
    response.raise_for_status()
    return response.json()

In the desktop client, this function is called automatically whenever the watched Word file is saved. Example usage from crelio_client/services/word_watch/winword.py:

from services.word_watch.uplaoder import upload_files_to_server

def on_change(doc_path, edit_id=None, auth_token=None, *args, **kwargs):
  pdf_path = smart_convert_to_pdf(doc_path)
  upload_files_to_server(docx_path=doc_path, pdf_path=pdf_path, edit_id=edit_id, auth_token=auth_token)