> ## 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. # File Transfer API > List, query and download files available for transfer on the Judit API. Update the status of each file after consumption for auditable flows. 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](/en/requests/custom-search)), use this API to list pending files, download via pre-signed URL and mark as consumed to avoid reprocessing. ## When to use Consume Custom Search results that arrive as files (CSV/JSON) instead of webhook. Receive periodic dumps of an entire portfolio (hundreds of thousands of lawsuits). Auditable trail of who downloaded each file and when β€” perfect for SOX/LGPD/GDPR. Integrate Judit into your data lake/warehouse via batch file consumption. *** ## πŸ” Authentication Every request must include a header with the company's API key: ```http theme={null} 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`: ```bash theme={null} curl -H "api-key: YOUR_API_KEY" \ "https://lawsuits.production.judit.io/transfer-file?page=1&page_size=20&status=[\"completed\"]" ``` ### Example response: ```json theme={null} { "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`: ```bash theme={null} curl -H "api-key: YOUR_API_KEY" \ "https://lawsuits.production.judit.io/transfer-file/be4ed52a-a96b-4782-a181-b7ed75cb2f21" ``` ### Example response: ```json theme={null} { "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`: ```bash theme={null} 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: ```json theme={null} { "status": "downloaded" } ``` To report an error: ```json theme={null} { "status": "error", "error_message": "Descrição do erro, stack trace ou contexto do problema." } ``` ### Example response - status `downloaded`: ```json theme={null} { "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 | HTTP | Reason | How to handle | | :---- | :-------------------------- | :------------------------------------------------- | | `400` | Invalid filter or status. | Validate query params before sending. | | `401` | API Key missing or invalid. | Check `api-key` header. | | `404` | File not found. | The `transfer_file_id` may be from another tenant. | | `429` | Rate limit exceeded. | Exponential backoff. | ## Next steps * [Custom Search](/en/requests/custom-search) β€” generate large reports. * [Webhooks](/en/webhook/callbacks) β€” get notified when a file is ready.