Classify Document

POST

api

classify

# Base64-encode the PDF, then send it
PDF_B64=$(base64 -i motion_for_sj.pdf)

curl -X POST https://api.courtrules.app/api/v1/classify \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d "{
\"judge_slug\": \"carol-bagley-amon\",
\"district_id\": \"edny\",
\"pdf_base64\": \"$PDF_B64\",
\"filename\": \"memo_in_support_sj.pdf\"
}"

import base64
from pathlib import Path

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Read and encode the PDF
pdf_b64 = base64.b64encode(Path("motion_for_sj.pdf").read_bytes()).decode()

# Classify the PDF
resp = requests.post(
    "https://api.courtrules.app/api/v1/classify",
    headers=headers,
    json={
        "judge_slug": "carol-bagley-amon",
        "district_id": "edny",
        "pdf_base64": pdf_b64,
        "filename": "memo_in_support_sj.pdf",
    },
)
result = resp.json()

# Add filing context, then send to /check
check_body = {
    **result["check_request"],
    "is_pro_se": False,
    "pmc_completed": True,
    "opposing_party_pro_se": False,
    "filing_role": "movant",
}
check_resp = requests.post(
    "https://api.courtrules.app/api/v1/check",
    headers=headers,
    json=check_body,
)

import { readFileSync } from "fs";

const pdfBase64 = readFileSync("motion_for_sj.pdf").toString("base64");

const classifyResp = await fetch("https://api.courtrules.app/api/v1/classify", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    judge_slug: "carol-bagley-amon",
    district_id: "edny",
    pdf_base64: pdfBase64,
    filename: "memo_in_support_sj.pdf",
  }),
});
const { check_request } = await classifyResp.json();

// Add filing context, then send to /check
const checkResp = await fetch("https://api.courtrules.app/api/v1/check", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ...check_request,
    is_pro_se: false,
    pmc_completed: true,
    opposing_party_pro_se: false,
    filing_role: "movant",
  }),
});

{
  "classification": {
    "document_scope": "brief_support",
    "motion_type": "Rule_56",
    "confidence": "high",
    "supported": true,
    "reasoning": "Document is titled 'Memorandum of Law in Support of Motion for Summary Judgment', contains Rule 56 references, and includes a statement of undisputed material facts."
  },
  "document": {
    "page_count": 31,
    "word_count": 10000,
    "caption": {
      "present": true,
      "has_court_name": true,
      "has_case_title": true,
      "has_docket_number": true,
      "has_document_designation": true
    },
    "sections": {
      "has_toc": true,
      "has_toa": true,
      "has_certificate_of_compliance": false,
      "has_certificate_of_service": true,
      "has_numbered_paragraphs": false,
      "has_56_1_statement": true,
      "has_56_1_counterstatement": false,
      "has_proposed_amended_pleading": false,
      "has_verbatim_discovery_text": false,
      "has_conferral_certification": false,
      "has_notice_of_motion": true,
      "has_memorandum_of_law": true,
      "has_supporting_affidavits": true,
      "has_pro_se_sj_notice": false
    }
  },
  "check_request": {
    "judge_slug": "carol-bagley-amon",
    "district_id": "edny",
    "document_scope": "brief_support",
    "motion_type": "Rule_56",
    "document": {
      "page_count": 31,
      "word_count": 10000,
      "caption": {
        "present": true,
        "has_court_name": true,
        "has_case_title": true,
        "has_docket_number": true,
        "has_document_designation": true
      },
      "sections": {
        "has_toc": true,
        "has_toa": true,
        "has_certificate_of_compliance": false,
        "has_certificate_of_service": true,
        "has_numbered_paragraphs": false,
        "has_56_1_statement": true,
        "has_56_1_counterstatement": false,
        "has_proposed_amended_pleading": false,
        "has_verbatim_discovery_text": false,
        "has_conferral_certification": false,
        "has_notice_of_motion": true,
        "has_memorandum_of_law": true,
        "has_supporting_affidavits": true,
        "has_pro_se_sj_notice": false
      }
    }
  },
  "page_count_analysis": {
    "total_pdf_pages": 35,
    "front_matter_pages": 2,
    "back_matter_pages": 2,
    "body_page_count": 31,
    "method": "llm_structural_analysis"
  },
  "format_detection": {
    "confidence": "high",
    "confidence_reason": "Font and margin data extracted successfully from PDF structure",
    "warning": null,
    "font_family": "TimesNewRoman",
    "font_name_raw": "ABCDEF+TimesNewRomanPSMT",
    "margins_per_side": { "top": 1.0, "bottom": 1.0, "left": 1.0, "right": 1.0 },
    "line_spacing_pt": 24.0
  }
}

POST /api/v1/classify

Upload a PDF and receive document classification (scope, motion type) plus a partial request body for the /check endpoint when the PDF is a supported federal filing. The API extracts page count, word count, structural metadata, and document type from the PDF automatically. You must add filing context fields (is_pro_se, pmc_completed, opposing_party_pro_se, filing_role) before sending to /check. The response includes a supported boolean indicating whether the document is a classifiable federal court filing. Non-federal documents, blank templates, court rules or practices, and non-legal documents return supported: false with confidence: "low" and no check_request. Uploaded PDFs are stored server-side for quality improvement. Note: May take 10-30 seconds to respond. Format extraction (font, margins, line spacing) has a 15-second timeout; fillable forms and interactive PDFs may hit this limit, in which case format checks are skipped and a warning is returned.

Try it

A sample filing PDF is available in the console playground. Upload it to see classification, extracted metadata, and a ready-to-run /check request body.

Request

string

required

Judge slug identifier (e.g. gary-r-brown)

string

required

District identifier (e.g. edny)

string

required

Base64-encoded PDF file.

string

Original filename of the PDF (e.g. motion_for_summary_judgment.pdf). Recommended: always include if available. Filenames like memo_in_support_sj.pdf provide a strong classification signal; generic names like document.pdf are still accepted but add no value.

# Base64-encode the PDF, then send it
PDF_B64=$(base64 -i motion_for_sj.pdf)

curl -X POST https://api.courtrules.app/api/v1/classify \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d "{
\"judge_slug\": \"carol-bagley-amon\",
\"district_id\": \"edny\",
\"pdf_base64\": \"$PDF_B64\",
\"filename\": \"memo_in_support_sj.pdf\"
}"

import base64
from pathlib import Path

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Read and encode the PDF
pdf_b64 = base64.b64encode(Path("motion_for_sj.pdf").read_bytes()).decode()

# Classify the PDF
resp = requests.post(
    "https://api.courtrules.app/api/v1/classify",
    headers=headers,
    json={
        "judge_slug": "carol-bagley-amon",
        "district_id": "edny",
        "pdf_base64": pdf_b64,
        "filename": "memo_in_support_sj.pdf",
    },
)
result = resp.json()

# Add filing context, then send to /check
check_body = {
    **result["check_request"],
    "is_pro_se": False,
    "pmc_completed": True,
    "opposing_party_pro_se": False,
    "filing_role": "movant",
}
check_resp = requests.post(
    "https://api.courtrules.app/api/v1/check",
    headers=headers,
    json=check_body,
)

import { readFileSync } from "fs";

const pdfBase64 = readFileSync("motion_for_sj.pdf").toString("base64");

const classifyResp = await fetch("https://api.courtrules.app/api/v1/classify", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    judge_slug: "carol-bagley-amon",
    district_id: "edny",
    pdf_base64: pdfBase64,
    filename: "memo_in_support_sj.pdf",
  }),
});
const { check_request } = await classifyResp.json();

// Add filing context, then send to /check
const checkResp = await fetch("https://api.courtrules.app/api/v1/check", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ...check_request,
    is_pro_se: false,
    pmc_completed: true,
    opposing_party_pro_se: false,
    filing_role: "movant",
  }),
});

{
  "classification": {
    "document_scope": "brief_support",
    "motion_type": "Rule_56",
    "confidence": "high",
    "supported": true,
    "reasoning": "Document is titled 'Memorandum of Law in Support of Motion for Summary Judgment', contains Rule 56 references, and includes a statement of undisputed material facts."
  },
  "document": {
    "page_count": 31,
    "word_count": 10000,
    "caption": {
      "present": true,
      "has_court_name": true,
      "has_case_title": true,
      "has_docket_number": true,
      "has_document_designation": true
    },
    "sections": {
      "has_toc": true,
      "has_toa": true,
      "has_certificate_of_compliance": false,
      "has_certificate_of_service": true,
      "has_numbered_paragraphs": false,
      "has_56_1_statement": true,
      "has_56_1_counterstatement": false,
      "has_proposed_amended_pleading": false,
      "has_verbatim_discovery_text": false,
      "has_conferral_certification": false,
      "has_notice_of_motion": true,
      "has_memorandum_of_law": true,
      "has_supporting_affidavits": true,
      "has_pro_se_sj_notice": false
    }
  },
  "check_request": {
    "judge_slug": "carol-bagley-amon",
    "district_id": "edny",
    "document_scope": "brief_support",
    "motion_type": "Rule_56",
    "document": {
      "page_count": 31,
      "word_count": 10000,
      "caption": {
        "present": true,
        "has_court_name": true,
        "has_case_title": true,
        "has_docket_number": true,
        "has_document_designation": true
      },
      "sections": {
        "has_toc": true,
        "has_toa": true,
        "has_certificate_of_compliance": false,
        "has_certificate_of_service": true,
        "has_numbered_paragraphs": false,
        "has_56_1_statement": true,
        "has_56_1_counterstatement": false,
        "has_proposed_amended_pleading": false,
        "has_verbatim_discovery_text": false,
        "has_conferral_certification": false,
        "has_notice_of_motion": true,
        "has_memorandum_of_law": true,
        "has_supporting_affidavits": true,
        "has_pro_se_sj_notice": false
      }
    }
  },
  "page_count_analysis": {
    "total_pdf_pages": 35,
    "front_matter_pages": 2,
    "back_matter_pages": 2,
    "body_page_count": 31,
    "method": "llm_structural_analysis"
  },
  "format_detection": {
    "confidence": "high",
    "confidence_reason": "Font and margin data extracted successfully from PDF structure",
    "warning": null,
    "font_family": "TimesNewRoman",
    "font_name_raw": "ABCDEF+TimesNewRomanPSMT",
    "margins_per_side": { "top": 1.0, "bottom": 1.0, "left": 1.0, "right": 1.0 },
    "line_spacing_pt": 24.0
  }
}

Response fields

object

Document type classification

Show Classification

string

Detected document type (e.g. brief_support, letter, affidavit). Omitted when supported is false.

string

Detected motion type, if applicable (e.g. Rule_56, discovery). Omitted for non-motion documents.

string

Classification confidence: high, medium, or low. A value of low means the document is not a supported filing type.

boolean

Whether the document is a classifiable federal court filing. Derived from confidence: true when confidence is high or medium, false when low.

string

Brief explanation of how the document was classified

object

Extracted document metadata including page count, word count, and structural elements detected in the PDF (caption, sections, format, privacy).

object

Present only when supported is true. A partial request body for POST /api/v1/check. Includes judge_slug, district_id, document_scope, motion_type (if detected), and the full document object. You must add is_pro_se, pmc_completed, opposing_party_pro_se, and filing_role before sending.

object

Breakdown of how body page count was computed from total PDF pages.

Show Page count analysis

integer

Total pages in the uploaded PDF.

integer

Pages of front matter (cover, TOC, TOA) excluded from body count.

integer

Pages of back matter (cert of service, cert of compliance, exhibits list) excluded from body count.

integer

Effective body page count used for limit checks (total minus front minus back).

string

Analysis method used for page counting.

object

Detected font, margin, and line spacing from the PDF. Used for formatting compliance checks.

Show Format detection

string

high, medium, or low. When low, format checks are skipped.

string

Why the confidence level was assigned.

string | null

Human-readable warning when format checks will be skipped or uncertain.

string | null

Font family name (e.g. TimesNewRoman). Null when detection failed.

string | null

Original font name as embedded in the PDF.

object | null

Margin measurements per side in inches (top, bottom, left, right). Null when detection failed.

number | null

Median line spacing in points. Null when detection failed.

string[]

Conditions that may affect result quality. Present only when something noteworthy occurred during analysis (e.g., format extraction failed, document was truncated).

Error responses

Code	Meaning
`400`	Invalid request (missing `pdf_base64`, invalid `judge_slug`, etc.)
`403`	District not accessible
`404`	Judge not found in the specified district
`429`	Rate limit exceeded (5 requests per minute)
`502`	Classification failed (timeout, upstream error)

Usage pattern

The typical supported-document flow is classify, then check:

POST /classify  →  get check_request  →  POST /check

When present, the check_request field contains everything the classifier can extract from the PDF. Before sending it to /check, add the filing context fields that only the filer knows: is_pro_se, pmc_completed, opposing_party_pro_se, and filing_role. When supported is false, show the classification reasoning to the user and do not call /check.

# Base64-encode the PDF, then send it
PDF_B64=$(base64 -i motion_for_sj.pdf)

curl -X POST https://api.courtrules.app/api/v1/classify \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d "{
\"judge_slug\": \"carol-bagley-amon\",
\"district_id\": \"edny\",
\"pdf_base64\": \"$PDF_B64\",
\"filename\": \"memo_in_support_sj.pdf\"
}"

import base64
from pathlib import Path

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Read and encode the PDF
pdf_b64 = base64.b64encode(Path("motion_for_sj.pdf").read_bytes()).decode()

# Classify the PDF
resp = requests.post(
    "https://api.courtrules.app/api/v1/classify",
    headers=headers,
    json={
        "judge_slug": "carol-bagley-amon",
        "district_id": "edny",
        "pdf_base64": pdf_b64,
        "filename": "memo_in_support_sj.pdf",
    },
)
result = resp.json()

# Add filing context, then send to /check
check_body = {
    **result["check_request"],
    "is_pro_se": False,
    "pmc_completed": True,
    "opposing_party_pro_se": False,
    "filing_role": "movant",
}
check_resp = requests.post(
    "https://api.courtrules.app/api/v1/check",
    headers=headers,
    json=check_body,
)

import { readFileSync } from "fs";

const pdfBase64 = readFileSync("motion_for_sj.pdf").toString("base64");

const classifyResp = await fetch("https://api.courtrules.app/api/v1/classify", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    judge_slug: "carol-bagley-amon",
    district_id: "edny",
    pdf_base64: pdfBase64,
    filename: "memo_in_support_sj.pdf",
  }),
});
const { check_request } = await classifyResp.json();

// Add filing context, then send to /check
const checkResp = await fetch("https://api.courtrules.app/api/v1/check", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ...check_request,
    is_pro_se: false,
    pmc_completed: true,
    opposing_party_pro_se: false,
    filing_role: "movant",
  }),
});

{
  "classification": {
    "document_scope": "brief_support",
    "motion_type": "Rule_56",
    "confidence": "high",
    "supported": true,
    "reasoning": "Document is titled 'Memorandum of Law in Support of Motion for Summary Judgment', contains Rule 56 references, and includes a statement of undisputed material facts."
  },
  "document": {
    "page_count": 31,
    "word_count": 10000,
    "caption": {
      "present": true,
      "has_court_name": true,
      "has_case_title": true,
      "has_docket_number": true,
      "has_document_designation": true
    },
    "sections": {
      "has_toc": true,
      "has_toa": true,
      "has_certificate_of_compliance": false,
      "has_certificate_of_service": true,
      "has_numbered_paragraphs": false,
      "has_56_1_statement": true,
      "has_56_1_counterstatement": false,
      "has_proposed_amended_pleading": false,
      "has_verbatim_discovery_text": false,
      "has_conferral_certification": false,
      "has_notice_of_motion": true,
      "has_memorandum_of_law": true,
      "has_supporting_affidavits": true,
      "has_pro_se_sj_notice": false
    }
  },
  "check_request": {
    "judge_slug": "carol-bagley-amon",
    "district_id": "edny",
    "document_scope": "brief_support",
    "motion_type": "Rule_56",
    "document": {
      "page_count": 31,
      "word_count": 10000,
      "caption": {
        "present": true,
        "has_court_name": true,
        "has_case_title": true,
        "has_docket_number": true,
        "has_document_designation": true
      },
      "sections": {
        "has_toc": true,
        "has_toa": true,
        "has_certificate_of_compliance": false,
        "has_certificate_of_service": true,
        "has_numbered_paragraphs": false,
        "has_56_1_statement": true,
        "has_56_1_counterstatement": false,
        "has_proposed_amended_pleading": false,
        "has_verbatim_discovery_text": false,
        "has_conferral_certification": false,
        "has_notice_of_motion": true,
        "has_memorandum_of_law": true,
        "has_supporting_affidavits": true,
        "has_pro_se_sj_notice": false
      }
    }
  },
  "page_count_analysis": {
    "total_pdf_pages": 35,
    "front_matter_pages": 2,
    "back_matter_pages": 2,
    "body_page_count": 31,
    "method": "llm_structural_analysis"
  },
  "format_detection": {
    "confidence": "high",
    "confidence_reason": "Font and margin data extracted successfully from PDF structure",
    "warning": null,
    "font_family": "TimesNewRoman",
    "font_name_raw": "ABCDEF+TimesNewRomanPSMT",
    "margins_per_side": { "top": 1.0, "bottom": 1.0, "left": 1.0, "right": 1.0 },
    "line_spacing_pt": 24.0
  }
}

Overview

Endpoints

Policies

Try it

Request

Response fields

Error responses

Usage pattern

​Try it

​Request

​Response fields

​Error responses

​Usage pattern

Try it

Request

Response fields

Error responses

Usage pattern