Engine API
← Web API

Engine API Reference

The Python rules engine handles all deterministic deadline calculations, jurisdiction rules, and PDF text extraction. No AI — pure code.

Base URL: http://engine:8000Format: JSONAll endpoints public (internal service)

⚡ Architecture Note

The engine is an internal microservice called by the Next.js web app. It is not exposed publicly in production. The web app's /api/calculate endpoint proxies to this engine. Dates are never computed by AI — the engine uses deterministic rule-based logic only.

POST/api/v1/calculate

Calculate a deadline date using jurisdiction-specific rules. Supports FL Rule 2.514, FRCP Rule 6(a), and FRAP Rule 26. Handles business days, holidays, weekend adjustments, and service method extensions.

Request Body

{
  "trigger_date": "YYYY-MM-DD (required)",
  "day_count": "integer >= 0 (required)",
  "computation_method": "auto | business_days | calendar_days | trial_period_countdown (default: auto)",
  "direction": "forward | backward (default: forward)",
  "jurisdiction": "FL-STATE | FL-17TH | FL-SDFL | FL-MDFL | FL-NDFL | FEDERAL | SD-FLA | 11TH-CIR (default: FL-STATE)",
  "service_method": "email | mail | hand | efiling | leave_at_office (optional)",
  "rule_reference": "string (optional, e.g. 'Fla.R.Civ.P. 1.440')",
  "trial_commencement_date": "YYYY-MM-DD (optional, for trial_period_countdown)"
}

Response

{
  "deadline_date": "YYYY-MM-DD",
  "trigger_date": "YYYY-MM-DD",
  "day_count": 30,
  "computation_method": "calendar_days",
  "direction": "forward",
  "jurisdiction": "FL-STATE",
  "service_addon_days": 0,
  "holidays_skipped": ["2026-05-25"],
  "weekends_skipped": ["2026-03-28", "2026-03-29"],
  "explanation": "Step-by-step text explanation",
  "steps": [
    { "step_number": 1, "description": "Start from trigger date", "date": "2026-03-01", "rule": null },
    { "step_number": 2, "description": "Count 30 calendar days", "date": "2026-03-31", "rule": "Fla.R.Civ.P. 2.514(a)" }
  ]
}

Example

curl -X POST http://localhost:8000/api/v1/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_date": "2026-03-01",
    "day_count": 30,
    "computation_method": "calendar_days",
    "direction": "forward",
    "jurisdiction": "FL-STATE"
  }'
POST/api/v1/calculate/batch

Batch calculate multiple deadlines in a single request. Useful for processing all deadlines from a court order at once. Each calculation is independent — failures in one don't affect others.

Request Body

{
  "calculations": [
    {
      "trigger_date": "2026-03-01",
      "day_count": 30,
      "computation_method": "calendar_days",
      "jurisdiction": "FL-STATE"
    },
    {
      "trigger_date": "2026-03-01",
      "day_count": 20,
      "computation_method": "business_days",
      "jurisdiction": "FL-STATE",
      "service_method": "mail"
    }
  ],
  "case_id": "string (optional)",
  "document_id": "string (optional)"
}

Response

{
  "results": [
    { "deadline_date": "2026-03-31", "trigger_date": "2026-03-01", "day_count": 30, ... },
    { "deadline_date": "2026-03-30", "trigger_date": "2026-03-01", "day_count": 20, ... }
  ],
  "total": 2,
  "success_count": 2,
  "error_count": 0
}

Example

curl -X POST http://localhost:8000/api/v1/calculate/batch \
  -H "Content-Type: application/json" \
  -d '{
    "calculations": [
      { "trigger_date": "2026-03-01", "day_count": 30, "jurisdiction": "FL-STATE" },
      { "trigger_date": "2026-03-01", "day_count": 20, "computation_method": "business_days", "jurisdiction": "FL-SDFL" }
    ],
    "case_id": "2026-CV-001234"
  }'
POST/api/v1/trial-order

Process a complete trial order and compute all standard deadlines. Generates pretrial deadlines, mediation deadlines, calendar call appearance, and optionally all trial period business days.

Request Body

{
  "order_date": "YYYY-MM-DD (required)",
  "trial_commencement_date": "YYYY-MM-DD (required)",
  "trial_duration_weeks": "1-12 (default: 4)",
  "jurisdiction": "FL-STATE | FL-17TH | FL-SDFL | FL-MDFL | FL-NDFL | FEDERAL | SD-FLA | 11TH-CIR (default: FL-STATE)",
  "calendar_call_date": "YYYY-MM-DD (optional)",
  "calendar_call_time": "string (optional, e.g. '1:00 PM')",
  "has_mediation_referral": "boolean (default: true)",
  "include_trial_days": "boolean (default: true)"
}

Response

{
  "order_date": "2026-06-01",
  "trial_commencement_date": "2026-10-05",
  "trial_duration_weeks": 2,
  "jurisdiction": "FL-STATE",
  "total_entries": 12,
  "deadlines": [
    {
      "entry_number": 1,
      "date": "2026-08-06",
      "category": "Deadline",
      "description": "Discovery cutoff — 60 days before trial period",
      "authority": "Fla.R.Civ.P. 1.280",
      "calculation_note": "60 calendar days before 2026-10-03 (trial period start)",
      "is_conditional": false
    },
    {
      "entry_number": 5,
      "date": "2026-07-15",
      "category": "Mediation",
      "description": "Mediation to be completed",
      "authority": "Fla.R.Civ.P. 1.720",
      "calculation_note": null,
      "is_conditional": true
    }
  ],
  "trial_days": {
    "start_date": "2026-10-05",
    "end_date": "2026-10-16",
    "duration_weeks": 2,
    "total_business_days": 10,
    "days": [
      { "date": "2026-10-05", "day_number": 1, "day_of_week": "Monday", "is_first_day": true, "is_last_day": false }
    ]
  }
}

Example

curl -X POST http://localhost:8000/api/v1/trial-order \
  -H "Content-Type: application/json" \
  -d '{
    "order_date": "2026-06-01",
    "trial_commencement_date": "2026-10-05",
    "trial_duration_weeks": 2,
    "jurisdiction": "FL-STATE",
    "has_mediation_referral": true,
    "include_trial_days": true
  }'
POST/api/v1/trial-period

Generate all business days in a trial period. Returns each weekday (excluding holidays) with day numbers, useful for trial calendars and scheduling.

Request Body

{
  "start_date": "YYYY-MM-DD (required, first day of trial)",
  "duration_weeks": "1-12 (required)",
  "jurisdiction": "FL-STATE | FL-17TH | FL-SDFL | FL-MDFL | FL-NDFL | FEDERAL | SD-FLA | 11TH-CIR (default: FL-STATE)"
}

Response

{
  "start_date": "2026-10-05",
  "end_date": "2026-10-16",
  "duration_weeks": 2,
  "total_business_days": 10,
  "days": [
    { "date": "2026-10-05", "day_number": 1, "day_of_week": "Monday", "is_first_day": true, "is_last_day": false },
    { "date": "2026-10-06", "day_number": 2, "day_of_week": "Tuesday", "is_first_day": false, "is_last_day": false },
    { "date": "2026-10-16", "day_number": 10, "day_of_week": "Friday", "is_first_day": false, "is_last_day": true }
  ]
}

Example

curl -X POST http://localhost:8000/api/v1/trial-period \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-10-05",
    "duration_weeks": 2,
    "jurisdiction": "FL-STATE"
  }'
GET/api/v1/rules/{jurisdiction}

Get all available rules for a jurisdiction. Returns an array of RuleInfo objects with rule numbers, trigger events, day counts, and computation methods. Jurisdiction values: FL-STATE, FL-17TH, FL-SDFL, FL-MDFL, FL-NDFL, FEDERAL, SD-FLA, 11TH-CIR.

Response

[
  {
    "jurisdiction": "FL-STATE",
    "rule_number": "1.440",
    "rule_title": "Setting Action for Trial",
    "trigger_event": "Order setting trial",
    "day_count": 30,
    "computation_method": "calendar_days",
    "direction": "backward",
    "service_addon": { "mail": 5, "email": 0, "hand": 0 }
  },
  ...
]

Example

curl http://localhost:8000/api/v1/rules/FL-STATE
GET/api/v1/holidays/{jurisdiction}/{year}

Get all observed holidays for a jurisdiction in a given year. Returns computed observed dates (e.g., if July 4 falls on Saturday, the observed date is Friday). Jurisdiction values: FL-STATE, FL-17TH, FL-SDFL, FL-MDFL, FL-NDFL, FEDERAL, SD-FLA, 11TH-CIR.

Response

[
  { "date": "2026-01-01", "name": "New Year's Day", "jurisdiction": "FL-STATE" },
  { "date": "2026-01-19", "name": "Martin Luther King Jr. Day", "jurisdiction": "FL-STATE" },
  { "date": "2026-02-16", "name": "Presidents' Day", "jurisdiction": "FL-STATE" },
  ...
]

Example

curl http://localhost:8000/api/v1/holidays/FL-STATE/2026
POST/api/v1/cases/detect

Detect case number and jurisdiction from document text using pattern matching. Returns the extracted case number, normalized form, detected jurisdiction, and confidence score. Falls back to needs_ai_extraction=true when patterns don't match.

Request Body

{
  "text": "string (required, document text to search)",
  "first_two_pages": "string (optional, just the first two pages for faster matching)"
}

Response

{
  "case_number": "24-CV-12345-SMITH",
  "normalized": "2024-CV-12345",
  "jurisdiction": "FL-SDFL",
  "confidence": 0.95,
  "needs_ai_extraction": false,
  "pattern_matched": "SDFL-civil"
}

Example

curl -X POST http://localhost:8000/api/v1/cases/detect \
  -H "Content-Type: application/json" \
  -d '{
    "text": "CASE NO.: 24-CV-12345-SMITH\nUNITED STATES DISTRICT COURT\nSOUTHERN DISTRICT OF FLORIDA"
  }'
POST/api/v1/extract-text

Extract raw text from a PDF document. Returns page-by-page text content for downstream processing.

Request Body

FormData: { file: File (PDF) }

Response

{
  "pages": [
    { "page": 1, "text": "ORDERED AND ADJUDGED that..." },
    { "page": 2, "text": "The defendant shall file..." }
  ],
  "total_pages": 12,
  "character_count": 24500,
  "extraction_method": "pdfplumber | ocr"
}

Example

curl -X POST -F "file=@court_order.pdf" http://localhost:8000/api/v1/extract-text
POST/api/v1/extract-markdown

Extract structured markdown from a PDF document. Preserves headings, lists, and table formatting for better AI comprehension.

Request Body

FormData: { file: File (PDF) }

Response

{
  "markdown": "# ORDER SETTING TRIAL\n\nThis cause coming before the Court...\n\n## ORDERED:\n\n1. Trial is set for **March 15, 2026**...",
  "total_pages": 12,
  "character_count": 22000,
  "extraction_method": "pdfplumber | ocr"
}

Example

curl -X POST -F "file=@court_order.pdf" http://localhost:8000/api/v1/extract-markdown
GET/health

Health check for the engine service. Returns status and version.

Response

{
  "status": "ok",
  "version": "1.0.0",
  "python_version": "3.12.x",
  "uptime_seconds": 86400
}

Example

curl http://localhost:8000/health

Web API Docs · jackson@docket4.me