API Documentation

Overview

This document describes the APIs provided by Umo Office Convert. This service is mainly used to convert Office documents and PDF documents into formats that can be viewed with Umo Office Viewer.

Basic Information

• Base URL: http://localhost:1236 (default port, configurable via environment variables)
• In non-production environments, you can access the Swagger UI via /openapi

Endpoints

1. Health Check

Check whether the service is running normally.

• URL: /
• Method: GET
• Description: Returns information indicating whether the service is running. If this route is not accessible, it indicates the service is not started or is unhealthy.

Response example:

{
  "code": 200,
  "success": true,
  "data": "Umo Office Convert service is running"
}

2. Convert by Uploading a File

Upload a file via a multipart form and convert it.

• URL: /convert/upload
• Method: POST
• Content-Type: multipart/form-data
• Parameters:
  • file: the file to be converted (required)

Response:

• On success, returns the converted file stream.
• On failure, returns a JSON error response.

Response headers:

• X-Task-Id: conversion task ID
• X-Request-Id: request id
• X-Document-Name: original document name
• X-Document-Summary: document summary
• X-Document-Name: original document name
• X-From-Cache: whether the result is served from cache
• Content-Disposition: file download information
• Content-Type: file type
• Content-Length: file size

Error response example:

{
  "code": 500,
  "success": false,
  "message": "Document conversion failed: an exception occurred during conversion"
}

3. Convert by JSON

Submit file information via JSON and convert it.

• URL: /convert
• Method: POST
• Content-Type: application/json
• Request body:

  {
    "path": "/path/to/document.docx",
    "filename": "document.docx"
  }

Response:

• On success, returns the converted file stream.
• On failure, returns a JSON error response.

4. Convert by URL

Submit file information via query parameters and convert it.

• URL: /convert
• Method: GET
• Parameters:
  • url: the file URL to convert (required, URL-encoded)
  • filename: original file name (required, URL-encoded)

Response:

• On success, returns the converted file stream.
• On failure, returns a JSON error response.

5. Download by Task ID

Download the converted file or the original file by conversion task ID.

• URL: /convert/{taskId}
• Method: GET
• Parameters:
  • taskId: task ID (path parameter)
  • target: file type to fetch. Values: converted (converted output) or original (original file). Default: converted.

Response:

• On success, returns the requested file stream.
• On failure, returns a JSON error response.

6. Get File Cover by Task ID

Get the file cover (i.e., the first page) by conversion task ID.

• URL: /convert/{taskId}/cover?size={size}
• Method: GET
• Parameters:
  • taskId: conversion task ID (path parameter)
  • size: cover size (query parameter)

Response:

• On success, returns the requested file stream.
• On failure, returns a JSON error response.

Supported File Formats

Umo Office Convert supports converting multiple office document formats. See: Supported File Formats.

Error Handling

When an error occurs, all endpoints return a unified JSON response:

{
  "code": 500,
  "success": false,
  "message": "error message"
}

Common status codes:

• 400: invalid request parameters
• 404: resource not found
• 500: internal server error

Webhook Notifications

The service supports using webhooks to receive notifications when file conversion completes. Configure CONVERTED_WEBHOOK_URL in environment variables. See: Environment Variables - Webhook.