Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.judit.io/llms.txt

Use this file to discover all available pages before exploring further.

The File Transfer API delivers large files generated by Judit — CSV/JSON exports from custom searches, on-demand reports, bulky aggregations — asynchronously, with auditable status (pending, available, consumed) per file.
🤖 Base URL: https://lawsuits.production.judit.io/. After generating a report (e.g. Custom Search), use this API to list pending files, download via pre-signed URL and mark as consumed to avoid reprocessing.

​
When to use

On-demand reports

Consume Custom Search results that arrive as files (CSV/JSON) instead of webhook.

Batch export

Receive periodic dumps of an entire portfolio (hundreds of thousands of lawsuits).

Audit

Auditable trail of who downloaded each file and when — perfect for SOX/LGPD/GDPR.

Data pipelines

Integrate Judit into your data lake/warehouse via batch file consumption.

​
🔐 Authentication

Every request must include a header with the company’s API key: 
api-key: YOUR_API_KEY
⚠️ A user may only access files belonging to their own company’s tenant.

​
📂 List available files

​
GET /transfer-file

Returns a paginated list of files available for the authenticated user’s company.

​
Supported query params:

  • description: string (filters by description)
  • file_type: csv, json, parquet
  • name: string (filters by file name)
  • status: string or array (e.g., status=completed or status=["completed","error"])
  • Dates: range filters for the fields below:
    • created_at, updated_at, completed_at, downloaded_at, error_at, failed_at, started_at
    • Example: created_at_gte=2025-04-01T00:00:00.000Z
  • Pagination and sorting:
    • page: page number (default: 1)
    • page_size: page size (max: 100, default: 10)
    • order_by: sorting field (default: created_at)
    • order: asc or desc (default: desc)

​
Example call with curl:

curl -H "api-key: YOUR_API_KEY" \
  "https://lawsuits.production.judit.io/transfer-file?page=1&page_size=20&status=[\"completed\"]"

​
Example response:

{
  "page": 1,
  "page_data": [
    {
      "transfer_file_id": "be4ed52a-a96b-4782-a181-b7ed75cb2f21",
      "description": "ARQUIVO INICIAL - CARGA 0",
      "file_type": "parquet",
      "name": "be4ed52a-a96b-4782-a181-b7ed75cb2f21-part-00001.parquet",
      "status": "downloaded",
      "created_at": "2025-04-22T11:50:00.000Z",
      "updated_at": "2025-04-22T09:21:06.343Z",
      "completed_at": "2025-04-22T11:51:00.000Z",
      "started_at": "2025-04-22T11:50:01.000Z",
      "downloaded_at": "2025-04-22T09:21:06.343Z",
      "error_at": "2025-04-22T09:20:31.460Z",
      "error_message": "teste de erro",
      "file_size": 0.038,
      "lawsuits_count": 19
    }
  ],
  "page_count": 1,
  "all_count": 1,
  "all_pages_count": 1
}

​
Explanation of return fields:

  • page: current page number
  • page_data: list of files returned on this page
  • page_count: number of records on this page
  • all_count: total number of files matching the filter
  • all_pages_count: total number of pages available

​
📥 Get the download URL

​
GET /transfer-file/:transfer_file_id

Returns the file’s metadata and a pre-signed AWS URL for download (valid for 5 minutes).

​
Example call with curl:

curl -H "api-key: YOUR_API_KEY" \
  "https://lawsuits.production.judit.io/transfer-file/be4ed52a-a96b-4782-a181-b7ed75cb2f21"

​
Example response:

{
  "transfer_file_id": "be4ed52a-a96b-4782-a181-b7ed75cb2f21",
  "description": "ARQUIVO INICIAL - CARGA 0",
  "file_type": "parquet",
  "name": "be4ed52a-a96b-4782-a181-b7ed75cb2f21-part-00001.parquet",
  "status": "completed",
  "created_at": "2025-04-22T11:50:00.000Z",
  "updated_at": "2025-04-22T09:21:06.343Z",
  "completed_at": "2025-04-22T11:51:00.000Z",
  "started_at": "2025-04-22T11:50:01.000Z",
  "file_size": 0.038,
  "lawsuits_count": 19,
  "pre_signed_url": "https://s3.amazonaws.com/..."
}

​
🛠 Update a file’s status

​
PATCH /transfer-file/:transfer_file_id

Lets you mark the file as downloaded or error after attempting to use it.

​
Example call with curl:

curl -X PATCH -H "api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"status": "downloaded"}' \
     "https://lawsuits.production.judit.io/transfer-file/be4ed52a-a96b-4782-a181-b7ed75cb2f21"

​
Request body:

To mark as downloaded: 
{
  "status": "downloaded"
}
To report an error: 
{
  "status": "error",
  "error_message": "Descrição do erro, stack trace ou contexto do problema."
}

​
Example response - status downloaded:

{
  "transfer_file_id": "be4ed52a-a96b-4782-a181-b7ed75cb2f21",
  "description": "ARQUIVO INICIAL - CARGA 0",
  "file_type": "parquet",
  "name": "be4ed52a-a96b-4782-a181-b7ed75cb2f21-part-00001.parquet",
  "status": "downloaded",
  "created_at": "2025-04-22T11:50:00.000Z",
  "updated_at": "202
4-04-22T11:50:00.000Z"
}

​
Common errors

HTTPReasonHow to handle
400Invalid filter or status.Validate query params before sending.
401API Key missing or invalid.Check api-key header.
404File not found.The transfer_file_id may be from another tenant.
429Rate limit exceeded.Exponential backoff.

​
Next steps