API Documentation

Complete reference for all available endpoints and payloads

🔍 Quick Navigation

Core Endpoints

Health Check

GET /health

Check if the API is running and healthy.

GET /health HTTP/1.1
Host: localhost:5001
{ "status": "ok" }
curl -X GET http://localhost:5001/health
import requests
response = requests.get('http://localhost:5001/health')
print(response.json())

File Upload

POST /upload

Upload a document file for data transformation and processing.

Parameters

ParameterTypeDescription
file RequiredfileDocument file (PDF, Excel, CSV, etc.)
lob RequiredstringLine of Business (GeneralLiability, Property, etc.)
POST /upload HTTP/1.1
Host: localhost:5001
Content-Type: multipart/form-data

file=@document.pdf
lob=GeneralLiability
{ "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }
curl -X POST http://localhost:5001/upload \
-F "file=@document.pdf" \
-F "lob=GeneralLiability"
import requests

files = {'file': open('document.pdf', 'rb')}
data = {'lob': 'GeneralLiability'}
response = requests.post('http://localhost:5001/upload', files=files, data=data)

Job Management

Get Job Status

GET /api/jobs/<job_id>

Retrieve the status and results of a specific job.

Parameters

ParameterTypeDescription
job_id Requiredstring (UUID)The unique job identifier
GET /api/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479 HTTP/1.1
Host: localhost:5001
{ "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "completed", "lob": "GeneralLiability", "created_at": "2025-11-24 10:30:45", "raw_data": "{...}", "result": "{...}", "validation_report": "{...}" }
curl -X GET http://localhost:5001/api/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479
import requests
response = requests.get('http://localhost:5001/api/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479')
print(response.json())

Submit Correction

POST /api/jobs/<job_id>/submit_correction

Submit corrected JSON to improve RAG system training data.

Parameters

ParameterTypeDescription
job_id Requiredstring (UUID)The unique job identifier
corrected_json RequiredstringCorrected JSON output as string
POST /api/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479/submit_correction HTTP/1.1
Host: localhost:5001
Content-Type: application/json

{ "corrected_json": "{...}" }
{ "message": "Correction submitted successfully", "example_id": "ex-12345-67890-abcde", "rag_enabled": true }
curl -X POST http://localhost:5001/api/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479/submit_correction \
-H "Content-Type: application/json" \
-d '{"corrected_json": "{...}"}'
import requests, json

corrected_data = {"policyNumber": "POL-001", "coverage": []}
response = requests.post(
f'http://localhost:5001/api/jobs/{job_id}/submit_correction',
json={'corrected_json': json.dumps(corrected_data)}
)

File Downloads

Download Original File

GET /download/file/<job_id>

Download the original uploaded file for a specific job.

Parameters

ParameterTypeDescription
job_id Requiredstring (UUID)The unique job identifier
GET /download/file/f47ac10b-58cc-4372-a567-0e02b2c3d479 HTTP/1.1
Host: localhost:5001
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"

(binary file data)
curl -X GET http://localhost:5001/download/file/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
-o original_document.pdf
import requests

response = requests.get('http://localhost:5001/download/file/f47ac10b-58cc-4372-a567-0e02b2c3d479')
with open('document.pdf', 'wb') as f:
f.write(response.content)

Download Result JSON

GET /download/result/<job_id>

Download the JSON result for a specific job.

Parameters

ParameterTypeDescription
job_id Requiredstring (UUID)The unique job identifier
GET /download/result/f47ac10b-58cc-4372-a567-0e02b2c3d479 HTTP/1.1
Host: localhost:5001
HTTP/1.1 200 OK
Content-Type: application/json
Content-Disposition: attachment; filename="result.json"

{ "policyNumber": "...", "coverage": [...], ... }
curl -X GET http://localhost:5001/download/result/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
-o result.json
import requests, json

response = requests.get('http://localhost:5001/download/result/f47ac10b-58cc-4372-a567-0e02b2c3d479')
result = response.json()
print(json.dumps(result, indent=2))

Download Schema

GET /download/schema/<lob>

Download the JSON schema for a specific line of business.

Parameters

ParameterTypeDescription
lob RequiredstringLine of Business (AccidentHealth, CyberLiability, FreightLiability, GeneralLiability, ManagementLiability, MarineCargo, PollutionLiability, ProfessionalIndemnity, Property)
GET /download/schema/GeneralLiability HTTP/1.1
Host: localhost:5001
HTTP/1.1 200 OK
Content-Type: application/json
Content-Disposition: attachment; filename="general_liability_schema.json"

{ "type": "object", "properties": {...}, "required": [...] }
curl -X GET http://localhost:5001/download/schema/GeneralLiability \
-o general_liability_schema.json
import requests, json

response = requests.get('http://localhost:5001/download/schema/GeneralLiability')
schema = response.json()
print(json.dumps(schema, indent=2))

Training Examples

Get Training Examples

GET /api/training_examples

Retrieve all training examples collected from user corrections. Useful for monitoring RAG system learning progress.

GET /api/training_examples HTTP/1.1
Host: localhost:5001
{ "count": 15, "rag_enabled": true, "examples": [ { "id": "ex-12345-...", "job_id": "f47ac10b-...", "lob": "GeneralLiability", "created_at": "2025-11-24 10:35:20" }, ... ] }
curl -X GET http://localhost:5001/api/training_examples
import requests

response = requests.get('http://localhost:5001/api/training_examples')
data = response.json()
print(f"Total examples: {data['count']}")
print(f"RAG enabled: {data['rag_enabled']}")

HTTP Status Codes & Errors

200 OK

Successful request

302 Found

Redirect (form-based upload)

400 Bad Request

Invalid parameters or missing required fields

404 Not Found

Resource (job, file, schema) not found

500 Server Error

Server error during processing

Complete Workflow Example

Here's a complete workflow demonstrating all key operations:

import requests, json, time

BASE_URL = "http://localhost:5001"

# 1. Health check
response = requests.get(f'{BASE_URL}/health')
print(f"✓ API Status: {response.json()['status']}")

# 2. Upload file
with open('policy.pdf', 'rb') as f:
  files = {'file': f}
  data = {'lob': 'GeneralLiability'}
  response = requests.post(f'{BASE_URL}/upload', files=files, data=data)
  job_id = response.json()['job_id']
  print(f"✓ Job created: {job_id}")

# 3. Poll job status
for attempt in range(30):
  response = requests.get(f'{BASE_URL}/api/jobs/{job_id}')
  status = response.json()['status']
  print(f" Attempt {attempt+1}: {status}")
  if status in ['completed', 'failed']:
    break
  time.sleep(2)

# 4. Download result
response = requests.get(f'{BASE_URL}/download/result/{job_id}')
result = response.json()
print(f"✓ Result: {json.dumps(result, indent=2)[:100]}...")

# 5. Submit correction (optional)
corrected = {"policyNumber": "POL-001", "coverage": []}
response = requests.post(
  f'{BASE_URL}/api/jobs/{job_id}/submit_correction',
  json={'corrected_json': json.dumps(corrected)}
)
print(f"✓ Correction submitted: {response.json()['example_id']}")

# 6. Get training examples
response = requests.get(f'{BASE_URL}/api/training_examples')
count = response.json()['count']
print(f"✓ Total training examples: {count}")

📚 Additional Resources

  • 📋 View Jobs - See all processing jobs
  • 📖 Training Examples - View RAG training data
  • 🏗️ System Architecture - Learn system design
  • 🔗 Postman Collection: Available at /docs/postman_collection.json
  • 📝 Full Documentation: Available at /docs/API_ENDPOINTS_DOCUMENTATION.md
Back to Jobs