API Docs

Date: 2026-05-20 | Version: 1.0

Table of Contents

API Documentation
Endpoints
1) Health Check
3) Translate (PDF or Images)
Example Requests
Prerequisites
Health
Ready
Translate one PDF and get translated PDF
Translate one PDF and get markdown text
Translate multiple images and get translated PDF
Translate multiple images and get markdown text
Error Cases
1) Missing `X-API-Key` header
2) Unknown `product_type`
3) Invalid API key for selected product
4) Product auth token env var missing on server
5) Invalid `response_format`
6) Missing files field
7) Mixed file types in one request (PDF + image)
8) Multiple PDFs in one request
9) Unsupported media type
10) Empty uploaded file
11) Uploaded image exceeds max size
12) Translation pipeline error
Quick Troubleshooting
API Documentation
Base URL: [Link]
Notes:
• OpenAPI/Swagger endpoints are disabled (docs_url=None, redoc_url=None,
openapi_url=None).
• Every protected request must include header X-API-Key.

Endpoints
1) Health Check
• Method: GET
• Path: /health
• Auth: Not required
• Purpose: Liveness probe
Successful response (200):
{
"status": "ok"
}

3) Translate (PDF or Images)

• Method: POST
• Path: /translate
• Content-Type: multipart/form-data
• Auth: Required (X-API-Key header)

Form fields
• files (required):
• Either exactly one PDF file, or
• One or more image files (image/jpeg, image/png, image/tiff, image/webp)
• Mixing PDF and image files in the same request is not allowed.
• product_type (required):
• Accepted values: compliance, secreterial, labour
• Used to validate X-API-Key.
• response_format (optional):
• binary (default): returns translated PDF bytes (application/pdf)
• text: returns translated markdown text (text/markdown)

Behavior summary
• PDF flow:
• Accepts only one PDF per request.
• Runs full document pipeline.
• Image flow:
• Accepts one or more image files.
 • Enforces per-file max size using Config.MAX_FILE_MB.

Successful responses
• 200 with application/pdf when response_format=binary
• 200 with text/markdown when response_format=text

Common error responses

• 400:
• Invalid response_format
• Missing files
• Mixed file types
• Multiple PDFs uploaded
• Empty uploaded file
• 401/403 (from auth validator): invalid API key for product type
• 413: uploaded image exceeds Config.MAX_FILE_MB
• 415: unsupported uploaded media type
• 500: translation pipeline failure

Example Requests
Prerequisites
• Start server (example):
python [Link]

• Set a reusable shell variable for the API key (optional):

export API_KEY="<your_api_key>"

Health
curl -X GET "[Link]

Ready
curl -X GET "[Link]

Expected:
{
"status": "ready"
}

Translate one PDF and get translated PDF

curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=compliance" \
 -F "response_format=binary" \
-F "files=@sample-files/[Link];type=application/pdf" \
--output [Link]

Expected:
• HTTP 200
• Content-Type: application/pdf
• Downloaded file: [Link]

Translate one PDF and get markdown text

curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=compliance" \
-F "response_format=text" \
-F "files=@sample-files/[Link];type=application/pdf"

Expected:
• HTTP 200
• Content-Type: text/markdown
• Response body contains translated markdown text

Translate multiple images and get translated PDF

curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=labour" \
-F "response_format=binary" \
-F "files=@[Link];type=image/png" \
-F "files=@[Link];type=image/png" \
--output translated_images.pdf

Expected:
• HTTP 200
• Content-Type: application/pdf
• Downloaded file: translated_images.pdf

Translate multiple images and get markdown text

curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=labour" \
-F "response_format=text" \
-F "files=@[Link];type=image/png" \
-F "files=@[Link];type=image/png"

Expected:
• HTTP 200
• Content-Type: text/markdown
Error Cases
The table below lists common failures with reproducible examples.

1) Missing `X-API-Key` header

• Status: 422 Unprocessable Entity
curl -X POST "[Link] \
-F "product_type=compliance" \
-F "response_format=text" \
-F "files=@sample-files/[Link];type=application/pdf"

Typical response:
{
"detail": [
{
"type": "missing",
"loc": ["header", "X-API-Key"],
"msg": "Field required"
}
]
}

2) Unknown `product_type`
• Status: 400 Bad Request
curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=unknown" \
-F "response_format=text" \
-F "files=@sample-files/[Link];type=application/pdf"

Typical response:
{
"detail": "Unknown product_type 'unknown'. Valid values: compliance, labour,
secreterial."
}

3) Invalid API key for selected product

• Status: 401 Unauthorized
curl -X POST "[Link] \
-H "X-API-Key: wrong-key" \
-F "product_type=compliance" \
-F "response_format=text" \
-F "files=@sample-files/[Link];type=application/pdf"

Response:
{
"detail": "Invalid API key."
}
4) Product auth token env var missing on server
• Status: 500 Internal Server Error
• Cause: server-side token env var is unset/empty (COMPLIANCE_API_AUTH_TOKEN,
SECRETERIAL_API_AUTH_TOKEN, or LABOUR_API_AUTH_TOKEN)
Notes:
• This is raised as RuntimeError in auth utility.
• Default FastAPI response may be a generic 500 payload depending on middleware.

5) Invalid `response_format`
• Status: 400 Bad Request
curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=compliance" \
-F "response_format=pdf" \
-F "files=@sample-files/[Link];type=application/pdf"

Response:
{
"detail": "Invalid response_format. Accepted values: 'binary', 'text'."
}

6) Missing files field

• Status: 422 Unprocessable Entity
curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=compliance" \
-F "response_format=text"

Typical response contains validation detail for missing form field files.

7) Mixed file types in one request (PDF + image)

• Status: 400 Bad Request
curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=labour" \
-F "response_format=text" \
-F "files=@sample-files/[Link];type=application/pdf" \
-F "files=@[Link];type=image/png"

Response:
{
"detail": "Mixed file types are not supported. Upload either one PDF or
one/more images."
}

8) Multiple PDFs in one request

• Status: 400 Bad Request
 curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=compliance" \
-F "response_format=binary" \
-F "files=@sample-files/[Link];type=application/pdf" \
-F "files=@sample-files/[Link];type=application/pdf"

Response:
{
"detail": "Only one PDF file may be uploaded at a time."
}

9) Unsupported media type

• Status: 415 Unsupported Media Type
curl -X POST "[Link] \
-H "X-API-Key: $API_KEY" \
-F "product_type=compliance" \
-F "response_format=text" \
-F "files=@[Link];type=text/plain"

Typical response:
{
"detail": "Unsupported file type 'text/plain' for '[Link]'. Accepted:
application/pdf or image/jpeg, image/png, image/tiff, image/webp."
}

10) Empty uploaded file

• Status: 400 Bad Request
Possible details:
• PDF path: Uploaded PDF is empty.
• Image path: Uploaded file '<filename>' is empty.

11) Uploaded image exceeds max size

• Status: 413 Payload Too Large
• Limit: Config.MAX_FILE_MB (from server config)
Typical response:
{
"detail": "'<filename>' exceeds the <MAX_FILE_MB> MB size limit."
}

12) Translation pipeline error

• Status: 500 Internal Server Error
Typical response:
{
"detail": "Translation failed: <reason>"
}
Quick Troubleshooting
• 422 usually means required header/form field is missing.
• 400 usually means invalid input combination or unsupported parameter value.
• 401 means auth key mismatch.
• 413 means image too large.
• 415 means unsupported uploaded file type.
• 500 means server-side configuration or translation pipeline failure.