Documentation Index
Fetch the complete documentation index at: https://docs.grigori.in/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Jobs API handles document conversion requests, allowing you to upload files, track conversion progress, and download results.
Create Job
Request
Content-Type: multipart/form-data
The document file to convert. Must be less than 100MB.
Output format for the converted document.Options:
md - Markdown formatjson - Structured JSON format
URL to receive job completion notifications.Format: Must be a valid HTTP/HTTPS URL
Enable OCR processing for images and scanned documents.
OCR provider to use when use_ocr is enabled.Options:
paddle - PaddleOCR (recommended)easyocr - EasyOCRmistral - Mistral AI (requires API key)
Response
Current job statusValues: pending, processing, completed, failed
Job progress percentage (0-100)
OCR provider used (when OCR is enabled)
Job creation timestamp (ISO 8601)
Last update timestamp (ISO 8601)
Webhook URL for notifications
curl -X POST "http://localhost:8000/api/v1/jobs" \
-F "[email protected]" \
-F "output_format=md" \
-F "webhook_url=https://your-site.com/webhook"
Response Example
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "pending",
"progress": 0,
"file_name": "document.pdf",
"output_format": "md",
"use_ocr": false,
"ocr_provider": "paddle",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z",
"webhook_url": "https://your-site.com/webhook"
}
Get Job Status
Request
The unique identifier of the job
Response
Current job statusValues:
pending - Job queued for processingprocessing - Currently being convertedcompleted - Conversion finished successfullyfailed - Conversion failed
Completion percentage (0-100)
Completion timestamp (only when status is completed or failed)
Error details (only when status is failed)
curl "http://localhost:8000/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000"
Response Examples
Pending
Processing
Completed
Failed
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "pending",
"progress": 0,
"file_name": "document.pdf",
"output_format": "md",
"use_ocr": false,
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z"
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "processing",
"progress": 45,
"file_name": "document.pdf",
"output_format": "md",
"use_ocr": false,
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:02:30Z"
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"progress": 100,
"file_name": "document.pdf",
"output_format": "md",
"use_ocr": false,
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:05:00Z",
"completed_at": "2024-01-15T10:05:00Z",
"metadata": {
"processing_time": 5.2,
"pages_processed": 10,
"file_size": 1024000
}
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "failed",
"progress": 0,
"file_name": "document.pdf",
"output_format": "md",
"use_ocr": false,
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:02:00Z",
"completed_at": "2024-01-15T10:02:00Z",
"error_message": "Unsupported file format or corrupted file"
}
Download Result
Request
The unique identifier of the completed job
Response
The response is the converted document file with appropriate headers:
MIME type based on output formatValues:
text/markdown; charset=utf-8 for Markdownapplication/json; charset=utf-8 for JSON
Filename for downloadFormat: attachment; filename="document.md"
curl "http://localhost:8000/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/result" \
-o converted_document.md
Error Responses
Bad Request - Job is not completed yet{
"detail": "Job is not completed yet"
}
Not Found - Job doesn’t exist or result file is missing{
"detail": "Job not found"
}
Job Status States
pending
Job has been created and queued for processing
processing
Document is currently being converted
completed
Conversion finished successfully, result is available
failed
Conversion failed, check error_message for details
Polling for Completion
import requests
import time
def wait_for_completion(job_id, timeout=300):
"""Wait for job completion with timeout"""
start_time = time.time()
while time.time() - start_time < timeout:
response = requests.get(f"http://localhost:8000/api/v1/jobs/{job_id}")
job = response.json()
if job['status'] == 'completed':
return job
elif job['status'] == 'failed':
raise Exception(f"Job failed: {job.get('error_message', 'Unknown error')}")
print(f"Progress: {job['progress']}%")
time.sleep(2)
raise TimeoutError(f"Job {job_id} did not complete within {timeout} seconds")
# Usage
job_id = "123e4567-e89b-12d3-a456-426614174000"
completed_job = wait_for_completion(job_id)
print(f"Job completed: {completed_job['id']}")
async function waitForCompletion(jobId, timeout = 300000) {
const startTime = Date.now();
while (Date.now() - startTime < timeout) {
const response = await fetch(`/api/v1/jobs/${jobId}`);
const job = await response.json();
if (job.status === 'completed') {
return job;
} else if (job.status === 'failed') {
throw new Error(`Job failed: ${job.error_message || 'Unknown error'}`);
}
console.log(`Progress: ${job.progress}%`);
await new Promise(resolve => setTimeout(resolve, 2000));
}
throw new Error(`Job ${jobId} did not complete within ${timeout}ms`);
}
// Usage
const jobId = "123e4567-e89b-12d3-a456-426614174000";
try {
const completedJob = await waitForCompletion(jobId);
console.log('Job completed:', completedJob.id);
} catch (error) {
console.error('Error:', error.message);
}
Rate Limiting
Rate limiting is not implemented in the current version. For production deployments, implement appropriate rate limiting middleware.
File Size Limits
Default limit: 100MB per fileConfiguration: Set MAX_FILE_SIZE environment variable (in bytes)
413 Request Entity Too Large error.
Supported File Types
Documents
PDF, DOCX, RTF, TXT, MD
Presentations
PPTX, PPTM, POTX, POTM
Spreadsheets
XLSX, XLSM, XLS, CSV
Images
PNG, JPG, GIF, BMP, WebP, TIFF
Next Steps
Health API
Check API health and readiness
Error Handling
Handle API errors properly
Webhooks
Set up real-time notifications
Examples
See complete integration examples
