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.

Cached response (cached_response)When you create a lawsuit or historical query, Judit first checks whether the data already exists in our database. If it does, we return the result immediately — both in the API response and via webhook (if registered) — with the field cached_response: true.In parallel, Judit triggers a fresh fetch against the courts. If anything has changed, you receive a second response with cached_response: false. That is the most up-to-date result.This is why it is normal to receive two seemingly identical webhooks for the same request_id:
  • The first one comes from cache (cached_response: true)
  • The last one is the updated result (cached_response: false)
Use this field to reliably identify which response represents the most recent state of the lawsuit.
The Asynchronous Lawsuit Query is the most complete and freshest way to fetch a lawsuit: Judit reaches the court in real time, downloads the full tree (cover, parties, lawyers, steps, classes, attachments) and returns it via webhook or polling.
🤖 The lawsuit search route operates asynchronously. The client application must make a POST /requests to start the search, wait for processing (via Webhook or by polling GET /requests/{id}), and, when the status is completed, capture the data via GET /responses.

​
When to use

Forced refresh

The lawsuit must reflect the latest court state — the datalake cache isn’t enough.

Full cover + steps

You need every cover field, all steps, attachments and relationships.

AI summary

Trigger judit_ia: ["summary"] to get a human-friendly summary ready for your UI.

Lawsuits under secrecy

Combine with the Credentials Vault to reach lawsuits that require court login.
If speed beats freshness (e.g. on-screen validation, interactive dashboard), use the Hot Storage Synchronous Query — millisecond response from Judit’s datalake.

​
Asynchronous flow (overview)

​
Understanding the Asynchronous Flow

Since data extraction directly from the courts can take a few seconds or minutes (depending on court instability), the Judit API uses an asynchronous request pattern. The flow consists of 3 simple steps:
  1. Create the request: You send the lawsuit number.
  2. Track the status: You check if the bot has finished the extraction.
  3. Capture the result: You consume the JSON with the lawsuit data.

​
Step 1: Creating the Search Request

To initiate a lawsuit search, make a POST request to the base requests route, sending the desired parameters in the body of the call.

​
Payload Parameters (Body)

Refer to the table below to configure your search, enable attachments, or trigger Judit AI:
ParameterTypeRequiredDescription
search.search_typestringYesDefines the entity being searched. For lawsuits, always use "lawsuit_cnj".
search.search_keystringYesThe lawsuit number in the CNJ standard (e.g., "0009999-99.9999.8.26.9999").
cache_ttl_in_daysintegerNoOptimizes the search by returning cached data if the lawsuit has already been queried within the last X days.
with_attachmentsbooleanNoIf true, Judit will download the lawsuit files.
judit_iaarrayNoList of AI features applied to the result. Send ["summary"] to receive a humanized summary of the header and case updates.
search_params.lawsuit_instanceintegerNoForces the search at a specific instance (e.g., 1 or 2).
Judit AI (Beta): The artificial intelligence feature (judit_ia) is in Beta. Response time may vary and the summary structure is subject to improvements.

​
Request Example (POST)

curl --location 'https://requests.production.judit.io/requests/' \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
    "search": {
        "search_type": "lawsuit_cnj",
        "search_key": "0009999-99.9999.8.26.9999"
    },
    "with_attachments": false
}'
Save the value of request_id, as you will need it for the next steps.
🚀 Shortcut: Automate with Webhooks (Recommended)If you have a Webhook URL configured, Steps 2 and 3 below are entirely optional. Instead of programming your application to keep polling the request status, the Judit API will send the found lawsuits incrementally directly to your server as soon as they are captured, finishing the flow with a request_completed event.👉 Learn how to configure and receive Webhooks here

​
Step 2: Check the Request Status

This step is crucial if you are not using Webhooks. Responses are inserted into the database incrementally as the bots interact with the court.
To find out whether the extraction has finished, query the request history endpoint passing the ID generated in Step 1: 
curl --location 'https://requests.production.judit.io/requests/<request_id>' \
--header 'api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data ''
Wait until the status property changes to "completed".

​
Step 3: Capture the Result (The Lawsuit)

As soon as the status is completed, you can retrieve the complete lawsuit data (and the AI summary, if requested).

​
Request example (GET)

curl --location 'https://requests.production.judit.io/responses?page_size=100&request_id=<request_id>' \
  --header 'api-key: '"$JUDIT_API_KEY"

​
Response examples

{
        "request_status": "completed",
        "page": 1,
        "page_count": 1,
        "all_pages_count": 1,
        "all_count": 1,
        "page_data": [
            {
                "request_id": "03abbf28-822e-45a0-a22c-098fbe157aa4",
                "response_id": "061c60b2-7fa9-4d20-87bb-1bedd31d5572",
                "origin": "api",
                "origin_id": "03abbf28-822e-45a0-a22c-098fbe157aa4",
                "response_type": "lawsuit",
                "response_data": {
                    "code": "9999999-99.9999.9.99.9999",
                    "justice": "8",
                    "tribunal": "26",
                    "instance": 1,
                    "distribution_date": "2019-02-15T16:00:00.000Z",
                    "judge": "Usuário teste",
                    "tribunal_acronym": "TJSP",
                    "secrecy_level": 0,
                    "tags": {
                        "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805",
                        "dictionary_updated_at": "2025-08-13T18:43:48.143Z"
                    },
                    "subjects": [
                        {
                            "code": "",
                            "name": "PAGAMENTO"
                        }
                    ],
                    "classifications": [
                        {
                            "code": "7",
                            "name": "PROCEDIMENTO COMUM CÍVEL"
                        }
                    ],
                    "courts": [
                        {
                            "name": "1ª Vara Cível"
                        }
                    ],
                    "parties": [
                        {
                            "main_document": "99999999999",
                            "name": "Usuário 2",
                            "side": "Passive",
                            "person_type": "Desconhecido",
                            "documents": [
                                {
                                    "document": "99999999999",
                                    "document_type": "cpf"
                                }
                            ],
                            "lawyers": [
                                {
                                    "name": "Usuário 3",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "main_document": "99999999999",
                            "name": "Usuário 4",
                            "side": "Active",
                            "person_type": "Desconhecido",
                            "documents": [
                                {
                                    "document": "99999999999",
                                    "document_type": "cnpj"
                                }
                            ],
                            "lawyers": [
                                {
                                    "name": "Usuário 5",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 4",
                            "side": "Active",
                            "person_type": "Desconhecido",
                            "documents": [],
                            "lawyers": [
                                {
                                    "name": "Usuário 5",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 2",
                            "side": "Passive",
                            "person_type": "Desconhecido",
                            "documents": [],
                            "lawyers": [
                                {
                                    "name": "Usuário 3",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 5",
                            "side": "Active",
                            "person_type": "Advogado",
                            "documents": []
                        },
                        {
                            "name": "Usuário 3",
                            "side": "Passive",
                            "person_type": "Advogado",
                            "documents": []
                        }
                    ],
                    "steps": [
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-07-16T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "56174b2e",
                            "content": "Início da Execução Juntado\n0003695-16.2019.8.26.0189 - Cumprimento de sentença",
                            "steps_count": 32,
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        },
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-06-06T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "939794b9",
                            "content": "Arquivado Definitivamente",
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        },
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-06-06T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "423978eb",
                            "content": "Trânsito em Julgado às partes\nCertidão de trânsito em julgado e remessa ao arquivo geral",
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        }
                    ],
                    "attachments": [
                        {
                            "attachment_id": "60153051-1-1",
                            "attachment_date": "2019-02-15T16:00:41.000Z",
                            "attachment_name": "Petição (Outras)",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153057-5-1",
                            "attachment_date": "2019-02-15T16:00:42.000Z",
                            "attachment_name": "Instrumento de Procuração",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153061-6-1",
                            "attachment_date": "2019-02-15T16:00:43.000Z",
                            "attachment_name": "Guia",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153064-7-1",
                            "attachment_date": "2019-02-15T16:00:44.000Z",
                            "attachment_name": "Guia",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        }
                    ],
                    "related_lawsuits": [],
                    "crawler": {
                        "source_name": "JSaj - TJ - SP - Lawsuit - Auth - 1 instance",
                        "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805",
                        "weight": 10,
                        "updated_at": "2025-08-13T18:43:47.770Z"
                    },
                    "metadata": {},
                    "county": "VARA JUIZADO ESP. CIVEL CRIM. DE FERNANDOPOLIS",
                    "amount": 5798,
                    "state": "SP",
                    "city": "FERNANDOPOLIS",
                    "justice_description": "JUSTIÇA ESTADUAL",
                    "last_step": {
                        "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                        "lawsuit_instance": 1,
                        "step_date": "2019-07-16T00:00:00.000Z",
                        "private": false,
                        "tags": {
                            "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805"
                        },
                        "step_id": "56174b2e",
                        "content": "Início da Execução Juntado\n0003695-16.2019.8.26.0189 - Cumprimento de sentença",
                        "steps_count": 32
                    },
                    "phase": "Execução ou cumprimento",
                    "status": "Ativo",
                    "name": "Usuário 4 X Usuário 2",
                    "created_at": "2025-08-13T18:43:51.016Z",
                    "updated_at": "2025-08-13T18:43:51.016Z",
                    "free_justice": false
                },
                "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
                "created_at": "2025-08-13T18:40:54.982Z",
                "request_created_at": "2025-08-13T18:40:54.037Z",
                "tags": {
                    "debug": true,
                    "dashboard_id": null,
                    "cached_response": false,
                    "cached": false
                }
            }
        ]
    }

​
What you receive back

The return is paginated and contains the Lawsuit Object inside the page_data array. If you requested Judit AI (use_judit_ia: true), the judit_ia object brings a human-readable summary of the lawsuit + structured listing of parties, classes, subjects and movements.
FieldTypeDescription
request_statusstringFinal request status (completed, created, processing).
page / page_count / all_pages_count / all_countnumberPagination.
page_dataarrayList of responses — usually 1 per request.
page_data[].response_typestringlawsuit, lawsuits, application_error, etc.
page_data[].response_dataobjectMain content — follows the Lawsuit Schema.
page_data[].cached_responsebooleantrue if it came from datalake; false if it came fresh from court.

​
Next steps